《代码整洁之道》第4章 注释 - 笔记

注释的恰当用法是弥补代码表达意图时遭遇的失败,良好的代码,让读者看代码就能明白含义。

代码在变动,在演化。注释并不总是随之变动。不准确的注释比没有注释要坏的多。注释算的上是一种没办法去除的恶。

注释不能美化代码

与其花时间编写解释你搞出糟糕代码的注释,不如花时间清洁那堆糟糕的代码

用代码阐述

省略注释,用代码代替,很多时候只需要创建一个描述与注释所言同一事务的函数即可。

好的注释

  • 版权及著作权声明的注释
  • 解释抽象方法返回值,不过这也能利用函数名表达,比如:

又比如:

把这代码移交给某个转换日期和时间格式的类中,注释显得就是多余。

  • 对意图的解释,解释写某个功能、某个函数的意图
  • 阐释返回值或者参数,能不用注释就不用。
  • 警示其它程序员
  • todo ,todo 应该解释为什么该函数部分无所作为,将来应该是怎样
  • 放大某种看来不合理之物的重要性,强调这段不合理代码的重要性。如:

坏注释

坏注释是对糟糕代码的支撑、借口,或者对错误决策的修正

  • 喃喃自语,可能对未来的自己写了一点不明确的注释,让外人看着很迷惑,未来自己看到也迷惑
  • 多余的注释
  • 误导性注释,语句有时难以精确用注释阐述,会漏掉一些信息或者含义有失偏颇。注释的意思要足够明确,假如代码出现2个数字,而注释没解释好,就会让人混乱。
  • 循规式注释,每个函数都要有 javadoc 或者每个变量要有注释的规矩简直可笑!
  • 日志式注释,在每个模块、新功能开始出添加一条注释,这种冗长的记录只会让模块变得凌乱不堪,应当全部删除
  • 废话注释,对显然意思加以注释,喋喋不休。
  • 能用函数或变量就别用注释,如下:
  • 位置标记注释,比如一排--------,如果比较少还可以,如果多了那就乱七八糟。
  • 被注释的代码,有了 git 和 ide 的历史版本,代码丢不了,尽管删!
  • 注释过多,别把一些和代码无关的注释写上,如果要写注释,一定要精炼。别写故事!
相关推荐
使二颗心免于哀伤23 分钟前
《设计模式之禅》笔记摘录 - 10.装饰模式
笔记·设计模式
悠哉悠哉愿意38 分钟前
【电赛学习笔记】MaxiCAM 项目实践——与单片机的串口通信
笔记·python·单片机·嵌入式硬件·学习·视觉检测
岩中竹2 小时前
广东省省考备考——常识:科技常识(持续更新)
笔记
Olrookie2 小时前
若依前后端分离版学习笔记(三)——表结构介绍
笔记·后端·mysql
rannn_1113 小时前
Java学习|黑马笔记|Day23】网络编程、反射、动态代理
java·笔记·后端·学习
UQWRJ3 小时前
菜鸟教程 R语言基础运算 注释 和数据类型
笔记
好心的小明6 小时前
【深度之眼机器学习笔记】04-01-决策树简介、熵,04-02-条件熵及计算举例,04-03-信息增益、ID3算法
笔记·算法·决策树
zhaoyang03018 小时前
vue3笔记(2)自用
前端·javascript·笔记
蒙塔基的钢蛋儿9 小时前
将nuttx构建脚本的文件夹复制修改为符号链接
笔记