阅读笔记 > 关于代码注释

关于代码注释

注释的种类可以分成五类：

代码的重复

重复的注释，用不同的词重申了代码的内容。它没有给读者提供代码的附加信息。

代码的解释

解释性注释，典型地用于解释复杂的，有效的和灵敏的代码段。这种情况下，他们是有用的，但常常是由于代码是易混淆的。假如代码复杂到需要解释，那么改进代码总比增加注释更好些。使代码本身清晰，然后使用总结或注释。

代码中的标记

标记注释并非是故意留在代码中的注释。它是给开发者的记录，表示工作还未做。一些开发者的标记注释为语法错误的标记（例如**），因而编译程序标记它并提醒他们要做更多的工作。其它开发者把一套特殊字符放人注释中，因而他们可以发现它们，但编译程序不能识别它们。

代码的总结

总结代码的注释做法是；它简化一些代码行成一或两句话。这样的注释比起仅重复代码而使读者比读代码更快的那种注释更有价值了。总结注释是相当有用的，特别是当其它人但不是代码的编者试图修改代码时。

代码意图的描述

意图这一层上的注释，解释了代码的目的。意图注释在问题一级上，而不是在答案一级操作。例如：
｛get current employee information｝获取当前雇员的信息
是一句意图注释，而
｛update Employee structure ｝修改雇员记录结构
是一句利用答案的总结描述。在 I BM六个月的学习，发现编程员最常说“理解最初的编程意图是最难的问题”（Fj el st ad 和 Haml en 1919）。意图注释和总结注释的区别不总是清楚的，但常常这不是重要的。意图注释的例子本章始终都给出了。

为全部代码接受的注释仅是意图和总结注释。

有效注释不是时间的浪费。太多注释和没有注释一样糟糕。你可采取一个合理的中间数量。

由于两种共同的原因，注释要花费许多时间去写。第一，注释可能会浪费时间或令人厌烦——脖子疼痛。假如这样，重写一个新的注释。需要许多繁重工作的注释是很令人头疼的。假如注释难于改变，他们就不必改变了；不准确和错误注释比根本没有注释更糟糕了。

第二，用语言描述程序做什么并不见得容易，所以注释会更难些。这常是你并不了解程序做什么的标志。你花在注释上的时间，应更好理解程序的真正时间，那是不管你是否注释都要花费的时间。

使用风格不应打断或妨碍修改

任何太具想象力的风格都会妨碍维护。例如，选取下面的注释部分将不便维护：
难以保存的注释类型的 Fort ran例子：

C  变量  含义C  …… ……C  XPOS..... X 坐标位置（以米为单位）C  YPOS..... Y 坐标位置（以十为单位）C  NPCMP..... 计算标志（=0 若不需要计算，C =1 若需要计算）C  PTGTTL.... 合计C  PTVLMX.... 最大值C  PSCCRMX.... 最大可能的值

假如你说这些起头的园点（⋯⋯）将难以维护，那么你就对了！他们看起来很好，但没有他们会更好些，他们将对修改注释的工作增加负担，你宁愿有准确的注释而不是好看的注释，假如有这种选择的话——常常是这样的。

下面是另一个难以维护普通风格的例子：

C语言的难以维护的注释风格的例子：

    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *    * 模型：GIGATROM.C *    * 作者：Dwight K.coder *    * 时间：2014 年 7 月 4 日  *    * *    * 控制二十一世纪程序的代 *    * 码开发工具。这些程序的 *    * 入口点在这个文件的底部的  *    * 行, 程序名为 Evaluatecode() *    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

这是一个好看的注释块。很清楚，整个块自成一体，并且块的开头和结尾都很明确。对这个块还不清楚的是它变化起来是否容易。假如你必须在注释底部增加文件名，那么你对右边漂亮的星号栏的就得重新编辑。假如你想要改变这段注释，那么你就要去掉左边和右边的星号。实际上这意味着这个块不便维护，因为要做比较多的工作。假如你按一个键便可得到几列整齐的星号，那就太好了。不要使用它，他们难以维护的问题不仅是在星号上面。下面的注释看起来并不好，但它肯定便于维护：

便于维护的 C语言的注释风格例子：

    /* * * * * * * * * * * * * * * * * * * * * * * * * * * *    模型：GIGATRON.C    作者：Dwight K.Coder    日期：2014 年 7 月 4 日    控制二十一世纪程序的代码    开发工具。这段程序的人口    在文件底部，程序名为 EvaluateCode()    * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

下面有一个极难维护的风格：
难于维护的 Basi c 语言的注释风格例子：

• 设置颜色枚举类型

  +——————————————————+．．．

• 设置菜单枚举变量

  +——————————————————+．．．

很难知道注释里破折号行起始和结尾的加号其值是多少？但容易猜出每次注释的变化，下划线不得不调整以使得结尾的加号处于正确的位置。当一个注释行被分成两行时你将如何办呢？你将怎么安放加号？去掉注释里的文字以使得它仅占据一行吗？使两行具有相同的长度？当你试图不断应用它时，这种办法的问题会很多。

关键点是应注意如何去分配你的时间。假如你花费了大量时间增加和删除破折号以使得加号对齐，你就无法编程了，而且是在浪费时间。找一个更有效的方式。在用加号下划线的情况中，可以进行选择，使得注释没有任何下划线。假如你需要使用下划线来强调，就找别的方法，而不用加号来对注释进行强调。一种办法就是用一个标准的下划线，不管注释的长度它都一样长。这样的线不需要维护，你可在开始位置用一个文字编辑宏来定义它。

使用 PDL编码过程来减少注释时间

假如写代码前你勾划了注释中的代码，便可通过几种方法实现。当你完成了代码，注释也就完了。在你填写低层的程序语言代码前，你可以获得高层 PDL。

在你进行过程中注释

写代码时，可以选择注释，直到工程结束再停止注释，这样做有很多的优点。在它自己的权限内，这变成了一项任务，使得看起来比每一次做一点时更有效率。以后再注释会花费更多的时间，因为你必须记住或算出代码在做什么而不是在书写你已想好的东西。因为你可能已忘记了设计中的假设和细节，所以这样也不会准确。

反对在进行编程时注释的观点认为“当你集中精力写代码时，不应当分散精力去写注释”。正确的答案是，假如你极其用心地写代码，注释会打断你的思路，你需要先设计 PDL，然后把PDL 转化成注释。需要集中精力编代码是一个警告信号，假如你的代码很难，在你对代码和注释担忧前应简化它。若你使用 PDL分类你的想法，编码是直接的而注释是自动的。

最佳数量的注释

工程有时采用一个标准，比如“程序必须至少每五行便有一行注释”。这个标准说明了程序员未写清晰代码的特征，且未指出原因。

若你有效地使用 PDL 编码过程，最后你会得出结论：第几行代码就要有一行注释。然而，注释的数量对过程本身来说是副作用。不能集中在注释的数量上，而是要集中是否每条注释都有效。假如明白了为什么写注释以及清楚了本章中涉及的其它法则，你就会有足够的注释了。

摘自《代码大全》