注释
- 若编程语言足够有表现力，我们就不需要注释。
- 注释总是一种失败。
- 代码在演化，注释却不总是随之变动。
- 不准确的注释比没注释坏的多。
1.用代码来阐述
- 创建一个与注释所言同一事物的函数即可// check to see if the employee is eligible for full benefits if ((employee.falgs & HOURLY_FLAG) && (employee.age > 65)) 应替换为if (employee.isEligibleForFullBenefits)
2.好注释
- 法律信息
- 提供基本信息，如解释某个抽象方法的返回值
- 对意图的解释，反应了作者某个决定后面的意图
- 阐释。把某些晦涩的参数或者返回值的意义翻译成可读的形式(更好的方法是让它们自身变得足够清晰，但是类似标准库的代码我们无法修改):if (b.compareTo(a) == 1) //b > a
- 警示。// don't run unless you have some time to kill
- TODO注释
- 放大 一些看似不合理之物 的重要性
3.坏注释
- 自言自语
- 多余的注释。把逻辑在注释里写一遍不能比代码提供更多信息，读它不比读代码简单。一目了然的成员变量别加注释，显得很多余。
- 误导性注释
- 遵循规矩的注释。每个函数都加注释、每个变量都加注释是愚蠢的。
- 日志式注释。有了代码版本控制工具，不必在文件开头维护修改时间、修改人这类日志式的注释
- 能用函数或者变量表示就别用注释:// does the module from the global list <mod> // depend on the subsystem we are part of? if (smodule.getDependSubsystems.contains(subSysMod.getSubSystem) 可以改为ArrayList moduleDependees = smodule.getDependSubsystems; String ourSubSystem = subSysMod.getSubSystem; if (moduleDependees.contains(ourSubSystem))
- 位置标记。标记多了会被我们忽略掉: ///////////////////// Actions //////////////////////////
- 右括号注释try { while { if { ... } // if ... } // while ... } // try 如果你想标记右括号，其实应该做的是缩短函数
- 署名 /* add by rick */ 源代码控制工具会记住你，署名注释跟不上代码的演变。
- 注释掉的代码。会导致看到这段代码其他人不敢删除
- 信息过多。别在注释中添加有趣的历史话题或者无关的细节
- 没解释清楚的注释。注释的作用是解释未能自行解释的代码，如果注释本身还需要解释就太遗憾了。
- 短函数的函数头注释。为短函数选个好名字比函数头注释要好。
- 非公共API函数的javadoc/phpdoc注释。
代码格式 1.垂直格式
- 短文件比长文件更易于理解。平均200行，最多不超过500行的单个文件可以构造出色的系统
- 区隔: 封包声明、导入声明、每个函数之间，都用空白行分隔开，空白行下面标识着新的独立概念
- 靠近: 紧密相关的代码应该互相靠近，例如一个类里的属性之间别用空白行隔开
- 变量声明应尽可能靠近其使用位置：循环中的控制变量应该总是在循环语句中声明。
- 成员变量应该放在类的顶部声明，不要四处放置
- 如果某个函数调用了另外一个，就应该把它们放在一起。我们希望底层细节最后展现出来，不用沉溺于细节，所以调用者尽可能放在被调用者之上。
- 执行同一基础任务的几个函数应该放在一起。
2.水平格式
- 一行代码不必死守80字符的上限，偶尔到达100字符不超过120字符即可。
- 区隔与靠近: 空格强调左右两边的分割。赋值运算符两边加空格，函数名与左圆括号之间不加空格，乘法运算符在与加减法运算符组合时不用加空格(a*b - c)
- 不必水平对齐。例如声明一堆成员变量时，各行不用每一个单词都对齐。
- 短小的if、while、函数里最好也不要违反缩进规则，不要这样: if (xx == yy) z = 1;