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

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

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

注释不能美化代码

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

用代码阐述

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

好的注释

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

又比如:

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

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

坏注释

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

  • 喃喃自语,可能对未来的自己写了一点不明确的注释,让外人看着很迷惑,未来自己看到也迷惑
  • 多余的注释
  • 误导性注释,语句有时难以精确用注释阐述,会漏掉一些信息或者含义有失偏颇。注释的意思要足够明确,假如代码出现2个数字,而注释没解释好,就会让人混乱。
  • 循规式注释,每个函数都要有 javadoc 或者每个变量要有注释的规矩简直可笑!
  • 日志式注释,在每个模块、新功能开始出添加一条注释,这种冗长的记录只会让模块变得凌乱不堪,应当全部删除
  • 废话注释,对显然意思加以注释,喋喋不休。
  • 能用函数或变量就别用注释,如下:
  • 位置标记注释,比如一排--------,如果比较少还可以,如果多了那就乱七八糟。
  • 被注释的代码,有了 git 和 ide 的历史版本,代码丢不了,尽管删!
  • 注释过多,别把一些和代码无关的注释写上,如果要写注释,一定要精炼。别写故事!
相关推荐
Z21-X7 小时前
云原生运维学习笔记:Kubernetes Volume 与 Secret 实验
运维·笔记·学习·云原生·kubernetes
一只大鸽子7 小时前
游戏开发笔记7-Godot RPG游戏基础-场景切换、全局脚本
笔记·游戏·godot
吃我一窝jio11 小时前
Docker+Jenkins+K8s全流程部署
java·开发语言·笔记·python
我超膨胀der.11 小时前
关于如何完整转移LABVIEW源码
笔记·labview
国科安芯11 小时前
FPGA上电偶发不启动:多轨电源时序、PGOOD与并联供电的FAE排查笔记——ASP4644S2B在星载智能处理板中的工程应用分析
笔记·单片机·嵌入式硬件·fpga开发·低轨卫星·抗辐射
一条破秋裤1 天前
【1115】【多线程】【笔记】
前端·chrome·笔记
神明不懂浪漫1 天前
【第八章】多线程(一)
java·开发语言·经验分享·笔记
星恒随风1 天前
MySQL 从零入门(九):事务管理详解——ACID、COMMIT、ROLLBACK、SAVEPOINT 与四种隔离级别
linux·服务器·数据库·笔记·mysql
蒸蒸yyyyzwd1 天前
秋招操作系统错题本
笔记·八股