第4章 注释

4.1 注释不能美化糟糕的代码

4.2 用代码来阐述

4.3 好注释

4.3.1 法律信息

4.3.2 提供信息的注释——函数

• 尽量利用函数名称传达信息
• 把这段代码转移到一个类里

  4.3.3 对意图的解释

  程序员某个决定后面的意图

  4.3.4 阐释——参数或返回值

  更好的方法是让足够清楚

  4.3.5 警示

  警告其他程序员
  代替以往的注释，现今用解释性字符串@Ignore属性来关闭某个特定的测试用例

  4.3.6 TODO注释

  4.3.7 放大作用——be careful

  放大某种不合理之物的重要性（容易被忽略的）

  4.3.8 公共API

  例如标准Java库中的Javadoc

4.4 坏注释

4.4.1 喃喃自语

只有自己才明白的东西

4.4.2 多余的注释

代码已经清楚

4.4.3 误导性的注释

容易让其它程序员根据注释去期望

4.4.4 循规式注释

每个函数、每个变量都要javadoc

4.4.5 日志式注释

版本控制系统取代

4.4.6 废话注释

4.4.7 可怕的废话

4.4.8 能用函数或变量时就别用注释

逻辑清晰，讲故事

ArrayList moduleDependees = smodule.getDependSubsystems(); 
String ourSubSystem = subSysMod.getSubSystem(); 
if (moduleDependees.contains (ourSubSystem)) {};

4.4.9 位置标记

应该只在特别有价值的时候用

// Action /////////////////////////////

4.4.10 括号后面的注释

也就是在长函数中间某个位置注释。
其实应该做的是从该处缩短函数。

4.4.11 归属与署名

版本控制系统可完全替代

// 严靖 2019.8.5日修改

4.4.12 直接注释掉代码

版本控制系统替代。
个人注：针对线上版本，开发过程仍然需要。

4.4.13 HTML注释

工具将注释抽取出来呈现到页面。
应该由工具完成而非HTML标签。

4.4.14 非本地信息

注释应描述离它最近的代码

4.4.15 信息过多

4.4.16 不明显的联系

注释本身都还需要解释

4.4.17 函数头

类似于javadoc

4.4.18 非公共代码中的javadoc

4.4.19 范例