【读书笔记】代码大全32章：自文档技术

• 外部文档
  • 大项目的文档往往放在源代码之外
  • 单元开发文件：是一种非正式的文件，给开发人员在开发的时候查看
  • 详细设计文档：描述类/方法级别的设计细节，是一种正式文档
• 良好的编程风格可以作为文档
• 到底要不要注释呢？
  
  • 良好的注释是很有价值的，但是不好的注释不但浪费时间，而且影响代码质量
• 良好注释的关键
  • 注释的种类
    • 重复代码的意思：完全没用
    • 解释代码：说明代码太复杂了，需要改进
    • 作为记号：最好使用标准化的记号，比如TODO记号
    • 代码的摘要：当别人需要修改代码时能起到很好的作用
    • 描述代码的意图：比代码摘要还要好用
    • 解释代码无法说明的问题，比如版本号、作者等：可以用javadoc中的标准记号来表示
  • 高效的注释方法
    • 写注释很花费时间
      • 保持注释风格很浪费时间
      • 代码的原理很难描述
    • 几点指导
      • 注释的风格不要太华丽，很难修改
      • 短注释用//，长注释用/**/
      • 将注释像代码一样整合在代码中
  • 应该写多少注释比较合适
    • 1条注释对应10行代码比较合适
    • 但是千万不能强制要求写注释，不然注释都是没有用的
• 注释技术
  • 对单行代码进行注释
    • 理由
      • 这行代码太复杂了，需要额外的解释
      • 这行代码曾经出现过错误，需要记下这种错误
    • 几点意见
      • 注释的时候不要想写什么就写什么
    • 注释放在一行代码的末尾
      • 问题
        • 这样的注释需要对齐，修改起来很麻烦
        • 这样的注释很难维护
        • 这样的注释往往解释不清，因为书写空间有限
        • 尽量不要把注释放在一行代码的末尾
        • 最根本的问题是单行代码其实很难写出有意义的注释
        • 这样的注释不要写给多行代码，容易造成误解
      • 什么时候应该使用这种注释
        • 注释变量的时候。不要在注释中写上缺陷的修复过程，注释要解释现在为什么可以用，而不是为什么以前不能用
        • 标记一个代码块的结束
  • 注释一段代码
    • 注释的时候主要写出代码的意图
    • 注释的时候关注为什么这样写，而不是这段代码的运行原理
    • 注释最好是代码预告，预告下一段代码准备做什么
    • 让每行注释有有它的价值
    • 记录代码中让人意想不到的事情，比如使用了特殊方法来提高性能，这时候要写明这种方式能提升多少性能
    • 注释的时候不要缩写
    • 注释分为主要注释和次要注释
      • // Major blablablabla
      • 大量代码
      • // ... minor blablabla 次要注释
      • 大量代码
      • // ... minor blablabla 次要注释
    • 注释库中的一些不明显的特性/BUG，并解释如何绕过这个特性/bug
    • 不要给误导性的代码加注释，要重写代码
  • 给变量增加注释
    • 注释变量的单位，米/毫米/秒/毫秒？
      • 可以在变量名称中包含变量的单位
    • 注释变量的取值范围
    • 注释编码的意思。比如1代表正常，0代表未审核，-1代表删除等
    • 如果变量是按位的话，注释每个位的含义。在网络编程中可能用到多一些
    • 注意，当变量的含义发生变化时，注释也要跟着变化
    • 注释全局变量的含义
  • 给控制结构增加注释
    • 控制结构的上一行往往都是用来放置注释的，解释代码的目的
    • 将代码放在if/case/loop/代码块的上一行
    • 将注释放在代码块结束的地方，比如
      • for(xxxIndex...){
      • ...
      • } // for xxxIndex - 处理每条用户记录
      • 这种注释往往意味着循环太复杂，需要改进
  • 给函数增加注释
    • 将注释放在离代码最近的地方
    • 在每个函数的顶部用一句或两句话描述函数
    • 给参数增加注释
      • 每行一个参数，每个参数一句注释
      • 也可以通过javadoc中的@param关键字来增加注释
      • 给参数写注释的时候要强调输出参数和输入参数的区别
      • 如果这个函数给参数作了假设，应当在注释中写出
    • 如果这个函数使用了全局变量，应当在注释中写出 
    • 注释这个函数的局限
    • 注释这个函数对全局变量的影响
    • 注释这个算法的来源（某某书第几页）
    • 在注释中写上标记，比如@keyword @param @author等
  • 给一个类增加注释
    • 描述类的设计思路
    • 在注释中写上类中包含的接口
    • 不要在注释中写上接口的实现细节
  • 给一个文件增加注释
    • 描述这个文件的目的
    • 如果这个类中包含多个类，应该在注释中注明为什么要多个类
    • 在注释中写上作者的详细信息，有助于团队协助
    • 在注释中写上版本信息
    • 法律信息
    • 文件名要和文件中的内容一致
  • 程序就像一本书
  • 序言
  • 目录
  • 章节
  • 参考
  • 这种结构详细描述了程序的高级接口和低级结构

• IEEE标准
  • 软件开发标准
    • IEEE Std 830-1998
    • IEEE Std 1233-1998
    • IEEE Std 1016-1998
    • IEEE Std 828-1998
    • IEEE Std 1063-2001
    • IEEE Std 1219-1998
  • 软件质量标准
    • IEEE Std 730-2002
    • IEEE Std 1028-1997
    • IEEE Std 1008-1987
    • IEEE Std 829-1998
    • IEEE Std 1061-1998
  • 管理标准
    • IEEE Std 1058-1998
    • IEEE Std 1074-1998
    • IEEE Std 1045-1992
    • IEEE Std 1062-1998
    • IEEE Std 1540-2001
    • IEEE Std 1490-1998