1、外部文档

  • 单元开发文件夹

    又称软件开发文件夹,是一种非正式的文档,包含了供开发者在编程期间使用的记录。

  • 详细设计文档

    详细设计文档是低层次的设计文档。描述在类层或子程序层的设计决定,曾考虑过的其他方案。

2、编程风格做文档

与外部文档相比,内部文档嵌入于程序本身,是最详细的文档,位于源码层次上。由于内部文档与代码的联系最密切,故也是代码修改后,最可能保持正确的文档。

3、注释或不注释

注释写的糟糕很容易,写的出色就难了。应该提成加注释,但也不能滥用注释。

4、高效注释之关键

  • 注释种类

    • 重复代码
    • 解释代码
    • 代码标记
    • 概述代码
    • 代码意图说明
    • 传达代码无法表达的信息
  • 高效注释

    • 采用不会打断或抑制修改的注释风格
    • 用伪代码编程去减少注释时间
    • 将注释集成到你的开发风格中
    • 性能不是逃避注释的好借口
  • 最佳注释量

    约每十条语句有一个注释,这样的密度时,程序清晰度最高。过多或过少的注释都会使得代码难以理解。

4、注释技术

  • 注释单行

    • 改行代码太复杂,因而需要解释
    • 该语句出过错,想记下这个错
    • 不要随意添加无关 注释
  • 行尾注释及其问题

    • 影响代码的视觉结构
    • 很难格式化,需要花费时间去对齐
    • 维护起来困难
  • 如何使用行尾注释

    • 不要对单行代码做行尾注释
    • 不要对多行代码做行尾注释
    • 行尾数据用于数据声明
    • 避免用行尾注释存放维护注记
    • 用行尾注释标记块尾
  • 注释代码块

    • 注释应表达代码的意图
    • 代码本身应该尽力做好说明
    • 注释代码段时应注重为何做而不是怎么做
    • 用注释为后面的内容做铺垫
    • 让每个注释都有用
    • 说明非常规做法
    • 别用缩略语
    • 将主次注释区分开
    • 错误或语言环境独特点都要加注释
    • 给出违背良好编程风格的理由
    • 不要注释投机取巧的代码,应重写之
  • 注释数据声明

    • 注释数值单位
    • 对数值的允许范围给出注释
    • 注释编码含义
    • 注释对输入数据的限制
    • 注释位标志
    • 将与变量有关的注释通过变量名关联起来
    • 注释全局数据
  • 注释控制结构

    • 应在每个if、case、循环或者代码段前加上注释
    • 应在每个控制结构后加上注释
    • 将循环结束处的注释看成是代码太复杂的征兆
  • 注释子程序

    • 注释应靠近其说明的代码
    • 在子程序上部用一两句话说明之
    • 在声明参数出注释这些参数
    • 利用诸如javadoc之类的代码说明工具
    • 分清输入和输出数据
    • 注释接口假设
    • 对子程序的局限性做注释
    • 说明子程序的全局效果
    • 记录所用算法的来源
    • 用注释标记程序的各部分
  • 注释类、文件和程序

    • 标注类的一般原则

      • 说明该类的设计方法
      • 说明局限性、用法假设等
      • 注释类接口
      • 不要在类接口处说明实现细节
    • 注释文件的一般原则

      • 说明各文件的意图和内容
      • 将姓名、电子邮件及电话号码放到注释块中
      • 包含版本控制标记
      • 请再注释快中包含法律通告
      • 将文件命名与其内容相关的名字
    • 程序注释

      • “序”为一组常见于文件头的注释,起到介绍程序的作用
      • “目录”给出顶层文件、类和子程序
      • “节”则是子程序内的各单位
      • “交叉引用”是代码的“参阅”映射

更多有关《代码大全 2》的读书笔记,请关注 :
http://tabalt.net/blog/code-complete-2-reading-notes/

本文链接:http://tabalt.net/blog/cc2-self-documenting-code/,转载请注明。