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

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

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

注释不能美化代码

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

用代码阐述

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

好的注释

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

又比如:

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

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

坏注释

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

  • 喃喃自语,可能对未来的自己写了一点不明确的注释,让外人看着很迷惑,未来自己看到也迷惑
  • 多余的注释
  • 误导性注释,语句有时难以精确用注释阐述,会漏掉一些信息或者含义有失偏颇。注释的意思要足够明确,假如代码出现2个数字,而注释没解释好,就会让人混乱。
  • 循规式注释,每个函数都要有 javadoc 或者每个变量要有注释的规矩简直可笑!
  • 日志式注释,在每个模块、新功能开始出添加一条注释,这种冗长的记录只会让模块变得凌乱不堪,应当全部删除
  • 废话注释,对显然意思加以注释,喋喋不休。
  • 能用函数或变量就别用注释,如下:
  • 位置标记注释,比如一排--------,如果比较少还可以,如果多了那就乱七八糟。
  • 被注释的代码,有了 git 和 ide 的历史版本,代码丢不了,尽管删!
  • 注释过多,别把一些和代码无关的注释写上,如果要写注释,一定要精炼。别写故事!
相关推荐
HuashuiMu花水木1 小时前
PyTorch笔记1----------Tensor(张量):基本概念、创建、属性、算数运算
人工智能·pytorch·笔记
笑衬人心。4 小时前
Ubuntu 22.04 修改默认 Python 版本为 Python3 笔记
笔记·python·ubuntu
金色光环4 小时前
【Modbus学习笔记】stm32实现Modbus
笔记·stm32·学习
zyxzyx6665 小时前
Flyway 介绍以及与 Spring Boot 集成指南
spring boot·笔记
西岭千秋雪_7 小时前
Redis性能优化
数据库·redis·笔记·学习·缓存·性能优化
HuashuiMu花水木8 小时前
Matplotlib笔记4----------图像处理
图像处理·笔记·matplotlib
DES 仿真实践家9 小时前
【Day 11-N22】Python类(3)——Python的继承性、多继承、方法重写
开发语言·笔记·python
IMPYLH15 小时前
Python 的内置函数 reversed
笔记·python
ysa05103018 小时前
数论基础知识和模板
数据结构·c++·笔记·算法
今天背单词了吗98019 小时前
算法学习笔记:7.Dijkstra 算法——从原理到实战,涵盖 LeetCode 与考研 408 例题
java·开发语言·数据结构·笔记·算法