3.注释(代码的整洁之道)

朱雀 2022-12-28 12:54 124阅读 0赞

# 3.注释(代码的整洁之道) #

--------------------

## 目录 ##

1.  注释不能美化糟糕的代码
2.  用代码来阐述
3.  好注释
4.  坏注释

注：代码的整洁之道PDF： [https://pan.baidu.com/s/16PLDWPiusGjcUfW\_jgOm5w][https_pan.baidu.com_s_16PLDWPiusGjcUfW_jgOm5w] 密码: s708

--------------------

### 1. 注释不能美化糟糕的代码 ###

1.  什么也不会比乱七八糟的注释更有本事搞乱一个模块，什么也不会比陈旧、提供错误信息的注释更有破坏性。
2.  注释的恰当用法是你不我们在用代码表达意图时遭遇的失败。
3.  如果你发现自己需要写注释，再想想看是否有办法翻盘，用代码来表达。
4.  注释会撒谎，存在的时间越久，就离其所描述的代码越远，越来越变得全然错误。原因很简单，程序员不能坚持维护注释。
5.  **代码在变动，在演变，但注释却不能随之变动。**
6.  真实只在一处地方有：代码。只有代码能忠实地告诉你它该做的事情。所以，尽管有时需要注释，也该多花心思尽量减少注释量。

--------------------

### 2. 用代码来阐述 ###

1.  示例一  
    ![在这里插入图片描述][20201217132839558.png]
2.  示例二  
    ![在这里插入图片描述][20201217132855768.png]
3.  你更愿意看到哪个示例？
4.  只要想上几秒钟，就能用代码解释你大部分的意图。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。

--------------------

### 3. 好注释 ###

1.  有些注释是必须的，也是有利的。不过**要记住，唯一真正好的注释是你想办法不去写注释。**

#### 1. 法律信息 ####

1.  公司代码规范要求编写与法律有关的注释，例如，版权及著作权声明就是必须和有理由在每个源文件开头注释防止的内容。  
    ![在这里插入图片描述][20201217133308634.png]

#### 2. 提供信息的注释 ####

1.  有时注释提供基本信息也有用处，例如，以下注释解释了某个抽象方法的返回值：  
    ![在这里插入图片描述][20201217165934434.png]
2.  这类注释有时很管用，但更好的方式是尽量利用函数名称传递信息。比如，在本例中，只要把函数重新命名为responderBeingTested，注释就是多余的了。

#### 3. 对意图的解释 ####

1.  有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。

#### 4. 阐释 ####

1.  有时，注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式，也会有用的。
2.  通常，更好的方法是尽量让参数或返回值自身就足够清楚。但如果参数或返回值是某个标准库的一部分，或是你不能修改的代码，帮助阐释其含义的代码就会有用。  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70]

#### 5. 警示 ####

1.  有时，用于警告其他程序员会出现某种后果的注释也是有用的。

#### 6. TODO注释 ####

1.  TODO注释解释了为什么该函数的实现部分无所作为，将来应该是怎样。  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70 1]
2.  TODO是一个程序认为该做，但由于某些原因目前还没做的工作。

#### 6. 放大 ####

1.  注释可以用来放大某种看来不合理之物的重要性。  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70 2]

--------------------

### 4. 坏注释 ###

1.  大多数注释都属于此类。通常，坏注释都是糟糕的代码的支撑或借口，或者对错误决策的修正，基本上等于程序员自说自话。

#### 1. 喃喃自语 ####

1.  如果只是因为你觉得应该或者因为过程需要注释，那就是无谓之举。如果你决定写注释，就要花必要的时间确保写出最好的注释。

#### 2. 多余的注释 ####

1.  下面代码展示了简单函数，其头部位置的注释全属多余，读这段注释花的时间没准比代码花的时间还要多。  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70 3]

#### 3. 误导性注释 ####

#### 4. 循规式注释 ####

1.  所谓每个函数都要有javadoc或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释只会搞乱代码，有可能误导读者。

#### 5. 日志式注释 ####

#### 6. 废话注释 ####

#### 7. 可怕的废话 ####

#### 8. 能用函数或变量时就别用注释 ####

1.  代码一  
    ![在这里插入图片描述][20201217210308820.png]
2.  可改成以下没有注释的版本  
    ![在这里插入图片描述][20201217210338420.png]
3.  作者应该重构代码，而不是写注释。

#### 9. 位置标记 ####

1.  程序员喜欢在源代码标记某个特别位置。如  
    ![在这里插入图片描述][20201217210454457.png]
2.  把特定函数放在这种标记栏下，多数时候实属无理，理当删除。

#### 10. 括号后面的注释 ####

1.  有时，程序员会在括号后面放置特殊的注释，尽管对含义深度嵌套结构的长函数可能有意义，但只会给我们更愿意编写的短小、封装的函数带来混乱。
2.  如果你发现自己想标记右括号，其实应该做的是缩短函数。

#### 11. 归属与署名 ####

1.  源代码控制系统非常清楚谁在何时添加了什么，没必要用那些小小的签名搞脏代码。
2.  注释在那放了一年又一年，越来越不准确，越来越和原作者没关系。  
    ![在这里插入图片描述][20201218102931502.png]

#### 12. 注释掉的代码 ####

1.  直接把代码注释掉是讨厌的做法，别那么干！

#### 13. HTML注释 ####

1.  源代码注释中的HTML标记是一种厌物。

#### 14. 非本地信息 ####

1.  假如你一定要注释，请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出系统级的信息。

#### 15. 信息过多 ####

1.  别在注释中添加有趣的历史性话题或者无关的细节描述。

#### 16. 不明显的联系 ####

1.  注释及其描述的代码之间的联系应该显而易见。

#### 17. 函数头 ####

1.  短函数不需要太多描述，为只做一件事的短函数选个好名字，通常比写函数头注释要好。

#### 18. 非公共代码中的javadoc ####

#### 19. 范例 ####

[https_pan.baidu.com_s_16PLDWPiusGjcUfW_jgOm5w]: https://pan.baidu.com/s/16PLDWPiusGjcUfW_jgOm5w
[20201217132839558.png]: /images/20221120/780ae238445040ef9b0c0440a2754fda.png
[20201217132855768.png]: /images/20221120/36c77db73c4e4ad682db014236bbfaad.png
[20201217133308634.png]: /images/20221120/4ca4457dda4d4a37be61f8cdbaeaa221.png
[20201217165934434.png]: https://img-blog.csdnimg.cn/20201217165934434.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20201217184729484.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20201217185055965.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20201217185513488.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20201217205719362.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MTkxMDY5NA==,size_16,color_FFFFFF,t_70
[20201217210308820.png]: https://img-blog.csdnimg.cn/20201217210308820.png
[20201217210338420.png]: https://img-blog.csdnimg.cn/20201217210338420.png
[20201217210454457.png]: https://img-blog.csdnimg.cn/20201217210454457.png
[20201218102931502.png]: https://img-blog.csdnimg.cn/20201218102931502.png