IT技术博客大学习 共学习 共进步
全部 移动开发 后端 数据库 AI 算法 安全 DevOps 前端 设计 开发者

提高代码可读性的注释技巧

本机暂存

   1. 逐层注释

   为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:

   针对每个类:包括摘要信息、作者信息、以及最近修改日期等;

   针对每个方法:包括用途、功能、参数和返回值等。

   在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如Java里的Javadoc)可以更好的推动注释工作完成得更好。

   代码可读性

   2. 使用分段注释

   如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下:

   // 检查所有结果的状态

   foreach (Record record in records)

   …{

    if (rec.checkStatus()==Status.OK)

    …{

    . . .

    }

   }

   // 开始执行事务

   Context ctx = new ApplicationContext();

   ctx.BeginTransaction();

   . . .

    3. 在代码行后添加注释

   如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:

   const MAX_ITEMS = 10; // maximum number of packets

   const MASK = 0x1F; // mask bit TCP

   4. 不要侮辱读者的智慧

   避免以下显而易见的注释:写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。

   if (a == 5) // if a equals 5

    counter = 0; // set the counter to zero

    5. 礼貌点

   避免粗鲁的注释,如:“注意,愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣,你也永远不知道谁将会阅读这些注释,可能是:你的老板,客户,或者是你刚才侮辱过的无能开发者。

   6. 关注要点

   不要写过多的需要转意且不易理解的注释,保持注释简单直接。

   7. 使用一致的注释风格

   一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何,Successful Strategies for Commenting Code已经规定和阐述了注释的一致性和针对的读者。注释应该是针对其他的开发者而言。

   8. 使用特有的标签

   在一个团队工作中工作时,为了便于与其它程序员沟通,应该采用一致的标签集进行注释。例如,在很多团队中用TODO标签表示该代码段还需要额外的工作。

   int Estimate(int x, int y)

   …{

    // TODO: implement the calculations

    return 0;

   }

    注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。

   9. 在代码时添加注释

   在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该write comments before code,用于理清头绪。例如:

   public void ProcessOrder()

   …{

    // Make sure the products are available

    // Check that the customer is valid

    // Send the order to the store

    // Generate bill

   }

    10. 为自己注释代码

   当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。

同分类推荐文章

  1. 科技爱好者周刊(第 401 期):如何赚到10亿美元 (2026-06-26 08:05:38)
  2. 如何做决策 - 从 Go 的一个 issue 说起 (2026-06-26 08:00:00)
  3. Seven Player:Windows上播放115网盘视频的增强工具 (2026-06-09 00:06:47)

查看更多 开发者 文章 →

建议继续学习

  1. 10个最“优秀”的代码注释 (累计阅读 4,764)
  2. 如何避免重构带来的危险 (累计阅读 4,637)
  3. 谈谈年度最佳代码“不管你们信不信,反正我信了” (累计阅读 4,129)
  4. 如何写出无法维护的代码 (累计阅读 4,020)
  5. 文字编排的易读性 (累计阅读 3,421)
  6. 一个实例:为什么注释是愚蠢的 (累计阅读 3,374)
  7. 代码的缩进和嵌套 (累计阅读 3,309)
  8. 10个最“牛叉”的代码注释 (累计阅读 3,104)
  9. 用 HTML 标记的古怪代码注释 (累计阅读 2,873)
  10. PHP最佳实践之PHP标签 (累计阅读 2,255)