还是认为这一章中作者对于注释的态度有点过于理想了,所以内容仅供参考
Tips
- 若编程语言足够有表达力,或者我们擅长用这些语言表达意图,就不那么需要注释,也许是根本不需要
- 我认为,如果注释能够清晰的表达代码的含义,对于回顾一些过去的项目是非常好的
- 注释的恰当用法是弥补我们再用代码表达意图时遭遇的失败
- 注释常常会与其所描述的代码分隔开来,越来越不准确
- 所以在维护代码的同时,也要相应的维护注释,防止注释和代码被分隔
- 程序员应当负责将注释保持在可维护、有关联、精确的高度
4.1 注释不能美化糟糕的代码
- 带有少量注释的整洁而有表达力的代码,要比带有大量注释的零碎而复杂的代码像样的多
4.2 用代码来阐述
- 很多时候,只需要在函数名称上讲功能描述清楚,就可以省去一段注释
4.3 好注释
- 有些注释是必须的,也是有利的
4.3.1 法律信息
- 公司代码规范要求编写与法律有关的注释
4.3.2 提供信息的注释
- 用注释来提供基本信息
4.3.3 对意图的解释
- 注释不仅提供了有关实现的有用信息,而且还提供了某个决定后面的意图
4.3.4 阐释
- 注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式
4.3.5 警示
- 用于警告其他程序员会出现某种后果的注释
4.3.6 TODO 注释
- 用
// TODO
形式在源代码中放置要做的工作列表- 例如某个代码结果中打算做到某个扩展,但是现在没做
- 按照现代 IDE 的功能,在每次提交代码时,都会给予提示
4.3.7 放大
- 注释可以用来放大某个看来不合理之物的重要性
4.3.8 公共 API 中的 Javadoc
- 没有什么比被良好描述的公共 API 更有用和令人满意了
4.4. 坏注释
- 都是糟糕代码的支撑或借口,或者是对错误决策的懒散修正,基本上都是这类程序员的自说自话,没有什么效果
4.4.1 喃喃自语
- 如果你决定写注释,就要花必要的时间确保写出最好的注释
- 任何迫使读者查看其它模块的注释,都是怀注释
4.4.2 多余的注释
- 读注释花的时间比读代码花的时间还要长
4.4.3 误导性注释
- 对代码描述不够精准
4.4.4 循规式注释
- 所谓每个函数都要有 Javadoc 或每个变量都要有注释的规矩完全是个笑话
4.4.5 日志式注释
- 在每次编辑代码时,都在模块开始处添加一条时间注释,这个已经没必要了,因为现在都有 代码版本控制系统( Git )
4.4.6 废话注释
- 对于显而易见的事喋喋不休,毫无新意
4.4.7 可怕的废话
- Javadoc 很有可能是废话
4.4.8 能用函数或变量时就别用注释
- 有时候为了把代码写的简洁,而进行了很长的嵌套,但是又担心别人看不懂,所以加了一些注释
- 这样的做法其实是本末倒置,不如直接把代码拆分出来写清楚
4.4.8.1 Bad Example
// 描述了下面这串代码的作用
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { … }
4.4.8.2 Good Example
- 将代码拆分后,层次变的更分明,更容易理解,注释也显得无关紧要了
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { … }
4.4.9 位置标记
- 尽量少用标记栏,只在特别价值的时候用
4.4.10 括号后的注释
- 如果发现自己想标记右括号,这就说明应该缩短函数,将这一段代码迁移到外部,单独作为一个函数在引入此处
4.4.11 归属和署名
- 代码版本控制系统非常善于记住 谁在何时添加了什么
- 没必要用那些各种格式的注释搞脏代码
- 代码版本控制系统才是这类信息最好的归属地
4.4.12 注释掉的代码
- 直接把代码注释掉是非常恶心的做法
- 可能当时你从某处复制过来一整段业务代码,但你只需要其中一部分,对于不需要的那些,暂时也没法确定以后需不需要(极大可能是因为懒得思考)
- 首先从其他地方复制整段代码就不是一个好兆头,其次如果非要复制,请一定搞清楚用途,留下需要的,删掉多余的,而不是注释多余的
4.4.13 HTML 注释
- 源代码注释中的 HTML 标记是一种废物
4.4.14 非本地信息
- 请确保注释描述了离它最近的代码
- 不要在本地注释的上下文环境中留下完全不相干的信息
4.4.15 信息过多
- 别再注释中添加无关的细节描述,没人有耐心去看完整段整段的注释内容
- 注释应该保持简洁的风格
4.4.16 不明显的联系
- 注释及其描述的代码之间的联系应该是显而易见的
- 注释的存在就是为了帮助理解,而不是混淆本意
- 注释的作用是解释未能自行解释的代码,如果注释本身还需要解释,就很无语了
4.4.17 函数头
- 短函数不需要太多描述
- 为只做一件事的短函数选一个好名字,要比写函数注释好的多
4.4.18 非公共代码的 Javadoc
- 虽然 Javadoc 对于公共 API 非常有用,但对于不打算作公共用途的代码就令人厌恶了
4.4.19 范例
- 列举了作者自己的一段代码优化效果