WdBly Blog

懂事、有趣、保持理智

周维的个人Blog

懂事、有趣、保持理智

站点概览

周维 | Jim

603927378@qq.com

推荐阅读

代码整洁之道 - 注释

读Robert C. Martin 的《clean Code》之《注释》章节记。

在学习如何为程序添加注释前,开发者需要了解一下几点。

  • 别给糟糕的代码加注释 —重新写吧。

    • —Brian W. Kernighan 与 P.J. Plaugher
  • 乱七八糟的注释最能搞乱一个模块

  • 陈旧、提供错误信息的注释具有更大的破坏性

注释的恰当用法是弥补我么在用代码表达意图的失败,这意味着我们在为程序添加注释时,总应该先考虑是否能通过代码来说明意图,而不是添加注释。

作者为什么在极力贬低注释呢?他的理由如下:

  • 注释会撒谎:也不是有意如此,注释存在的事件越久,就离其描述的代码越远,原因在于程序员不能坚持维护注释。

不要为糟糕的代码加注释

写注释的常见动机之一是糟糕的代码存在,当编写了一个令人困扰且乱七八糟的模块后,我们告诉自己“还是写点注释吧”。

不,好的做法是把糟糕的代码弄干净。

好的注释

有些注释是必须的,对程序也是有利的。

法律信息

在一些开源项目中,通常会将版权等法律相关信息作为注释放到代码的开头。

注意最好不要将所有条款作为注释引入,而是指向其他的外部文档。

解释意图

很多时候在阅读他人的代码时,我们会对作者为什么这个做感到困惑,这种提供某个决定后的意图类的注释也是必须的。

警示

用于警示其他程序员会出现某些后果的注释也是有用且有利的。

坏的注释

大多数的注释都属于此类。

喃喃自语

自顾自的写了一堆解释不明确的注释,会导致阅读代码的人更加困惑

多余的注释

多余的注释往往提供不了比代码更多的信息,读它也并不比读代码容易,它就像一个二手车贩子,满口保证你不用打开发动机检查。

误导性的注释

有时候你的注释和你的代码是不完全吻合的,这会对其他开发者造成误导。这位可怜的开发者可能会花费一个下午的时间拼命的寻找Bug的位置。

循规式的注释

为每个函数、每个参数、每个变量编写注释的规矩是非常愚蠢而可笑的,这会让代码变得散乱,满口胡言,令人费解。

日志式的注释

在文件的开头添加日志类的注释也是不可取的,这类日志类的注释标明了代码的修改和commit。

在有了代码管理系统(Git)后,删掉这些没用的注释吧。

废话注释

用整理代码的决心替代创作废话的冲动吧,你会更加优秀。

注释掉的代码

曾经的程序员担心丢失一些暂时不用的重要代码,将代码给注释起来,还是那句话

在有了代码管理系统(Git)后,删掉这些没用的注释吧。

结尾

好的代码中不会有大量的坏的注释,希望引以为戒。

提交

全部评论0

暂时没有评论...