代码大全2阅读笔记_第32章-自说明代码

代码大全2阅读笔记_第32章-自说明代码

文章的开头，我们先来看一则关于注释的讨论，摘自代码大全。

--------------------------------------个人阅读笔记---------------------------------------

1、外部文档

• 1.1 单元开发文件夹
  常用于记录功能开发期间相关的记录，可以是图片，表格，文字等格式，对内容没有要求，仅供开发期间跟内部使用。
• 1.2 详细设计文档
  描述类层或子程序层的设计方案，以及采用所选用方案的理由。

2、编程风格作文档

很多时候，我们的代码缺乏的不是注释，而是良好的代码风格。我们仅仅只需要改进我们的代码风格就能大大改善我们的阅读代码体验。
对应精美的代码而言，注释只是一个小小的装饰物而已。我们写注释的时候，尽量多写为什么我们要这么做，而不是去描述这段代码干了些什么，干了什么在代码中已经写的很清楚了，不要试图用注释去掩盖糟糕的代码，请重构你的代码。

3、注释或不注释

写注释能让你更好的思考代码在干什么。如果注释困难，要么是因为代码太垃圾，要么是没有理解透彻这部分代码。我们应该写注释，但不能滥用注释。

4、高效的注释

糟糕的注释种类：

• 重复代码。只是用文字把代码的工作由描述一次，这样的注释除了增加阅读量以外，没有提供其它有效的信息
• 解释代码。我们通常因为代码比较复杂而产生一些解释性注释，试图以注释消除阅读代码者的疑惑。如果因为代码比较复杂而需要注释，最好改进代码。

有效的注释种类

• 代码标记。用于提醒开发者有哪些地方未完成，有哪些地方需要注意，但是请采用合理的，固定的标记。
• 概述代码。将若干代码以一两句注释描述清楚，这对于阅读你代码的其它开发者来说尤其有用。
• 代码意图说明。目的性代码用来说明一段代码的意图，它指出要解决的问题，而非解决的方法。
• 传达代码无法表述的信息。例如与代码设计相关的注意事项。对于完工的代码，只允许有三种注释：目的性注释，概述性注释，代码无法表述的信息

不要用难以维护的注释风格，有的注释虽然看上去美观，但可能会由于注释难以维护导致注释与代码不一致。如果要花费很多时间来让注释中一些奇怪的+，*等符号对齐，无疑是一场灾难。

难以维护的注释风格示例：
容易维护的注释风格示例：

5、注释技术

• 不要写无关的注释。不要写神秘的注释。
• 行尾注释通常只是在特定的情况使用。例如数据声明。
• 不要单行注释，只对某个片段或方法添加注释。
• 注释应表达代码的意图，描述为什么要这么做。
• 注释要易于维护，靠近被注释的代码，采用易于维护的注释风格。