本章主要介绍的是如何正确的使用注释，并写出高质量高标准的注释。但是作者开篇之初的“注释总是一种失败”的观点我是不敢苟同的，但本着求同存异以及学习的心态，本章中好多观点还是值得我去学习和借鉴的。
作者开篇指出，“注释总是一种失败”。这句话，其实很容易让人误解，但结合作者上下文的内容，你又会发现该观点也不无道理。实际上作者并不反对注释，作者只是反对滥用注释。为什么这么说。主要有以下几点：
- 给糟糕的代码添加注释，不如写出整洁而有力的代码。
- 添加注释没有统一的规范和标准，被开发人员滥用。
- 添加的注释往往并不准确，表意并不清楚。
- 后期开发人员往往只维护代码，而忽略注释的同步维护与更新，导致注释最后词不达意，甚至到后期与被注释的代码所表达的意思完全是南辕北辙。
- 整洁而高质量的代码，如果做到了所见即所得，并不需要太复杂或者过于详细的注释。
- 开发人员往往给“烂”代码，添加注释，以来矫正，而忽略的代码的高质量才是根本。
- 过多的注释，尤其是大部分注释，均被滥用，不规范、词不达意、过期、多余、冗余、具有误导性、存在开发人员个人特质，造成代码繁琐混乱、质量低下，也完全违背了代码整洁的原则。
个人认为，代码是需求另一种形式的阐述。如果说被编译后的代码（往往被编译成客户端，网站，PC客户端，手机APP）是面向客户的，供客户使用；那么未被编译的代码（通常指项目源码）就是面对开发人员的，供开发人员阅读和使用。客户在使用软件的时候，往往需要说明书或者相关引导；那么开发人员，在使用源码的时候同样也需要说明书或者相关引导。那么开发人员究竟需要什么样的说明书或引导呢，在我看来包含两点：详细设计文档和代码注释。详细设计不在此讨论范围内，暂且不提。所以，在我看来代码注释是必不可少的。注释不仅能够让开发人员，尤其是后来开发人员（可能是新人，也可能是其他不熟悉的内部开发人员），快速了解该部分代码的功能，还能在一定程度上了解需求，尤其是在这个提倡敏捷开发、小步快跑的互联网年代，在一定的程度上能够提升开发人员的开发效率，提升代码可读性，也能够降低后来人熟悉代码的要求，加快后来人熟悉业务和代码的效率，帮助后来人尽快进入到开发阶段，进而降低开发成本，提高团队整体开发效率，于团队、于公司来讲都是有益的。我们真正要面对的是如何使用好注释。下面是结合本章内容以及个人经历的几点看法：
- 统一代码注释规范，统一代码注释风格。
- 注释要精简，表意要清楚，不可冗余，不可啰嗦，更不要带有个人色彩，要与代码表意保持一致。
- 注释要注意词意语意，不可二义性，避免产生歧义，造成误导。
- 注释要伴随代码的更新和维护，同步得到更新和维护。
- 当发现需要大量注释，才能解释清代码的时候，应停止添加注释，而是回头整理和调整代码逻辑，对代码进行合理有效的细化和拆分。
- 通过正确而恰当的命名，尽量让变量名、参数名、函数名、类名、包名等做到命名所见即所得，降低注释的复杂度，甚至可以因此而省略注释。
- 注释尽量围绕，是什么，做什么，什么做什么以来得到什么，为了防止什么要（不要）做什么，要做到简洁性，概括性。
- 删除不必要的注释，冗余（尤其废话特别多的）注释，修正错误以及误导性注释，简洁和调整必要注释。
- 对于开发阶段的，调试注释，日志注释，FIX\TODO注释，诸如类似的注释要及时清理和删除。
- 过期的代码和注释也要及时或者定期删除。
- 建议暴露给外部的公共属性或者方法一定要添加注释，特别是框架类的代码库。内部私有不外漏的代码，要根据相关逻辑复杂度，酌情添加注释，但是一定要精简，具备概括性，这里特别建议回头看看第四点。
- 对于业务逻辑复杂的部分代码，添加简洁的概括性的注释的同时，可以关联相关需求文档或者详细设计文档。
- 编写功能模块相关开发文档，尤其是特别复杂的功能模块，该文档至少要包括设计思路，实现方案，注意事项，具体细节可根据具体情况酌情介绍。相当于将该功能模块的注释更详细化细节化，然后在代码模块中关联该开发文档。
可加群一起交流共同学习：801216530。
