1.5 写好注释，真的是小菜一碟吗？

本文内容是极客时间课程——代码精进之路中代码规范篇的学习笔记。

 

1.注释的无奈的妥协

因为注释不需要运行，所以没有常规的办法来测试它。

注释难以维护，这是使用注释带来的最大的麻烦。

注释为我们提供了一个借口。

注释的目的是让其他人能更好地理解我们的代码，对于大部分程序员来说，问题还是注释太少，而不是太多。

 

2.几种常见的注释类型

（1）记录源代码的版权和授权。一般来说，版权和授权信息是固定的，需要注意的是，如果文件有变更，记得更改版权信息的年份。

 

/*
* Copyright (c) 2018, FirstName LastName. All rights reserved.
*/

 

（2）用来生成用户文档

比如javadoc，帮助软件的使用者了解软件的功能和细节。

 

（3）用来解释源代码

 

3.简化注释的风格

（1）对于版权和授权的注释，使用多行注释，文字和星号之间使用一个空格，注释行长度限制与代码保持一致。

 

（2）对于文档注释，使用javadoc要求的格式。

 

（3）对于第三种注释，使用单行注释//

 

4.如果一段代码不再需要，我会清理掉代码，而不会保留这个注释掉的代码块。不要在源代码里记录代码历史，那是代码版本管理系统该干的事情。

 

5.注释的三项原则

 

（1）准确，错误的注释比没有注释更糟糕；

（2）必要，多余的注释浪费阅读者的时间；

（3）清晰，混乱的注释会把代码搞得更乱；

 

6.注释的反面案例和修改方案

 

（1）准确的注释

 

（2）多余的注释

 

（3）注释和代码不能从视觉上清晰地分割，注释会破坏代码的可读性

 

（4）不要在代码里标注想要做和已经做过的工作，记录代码的变更记住，以及注释掉的调试代码