如何帮助未来的开发者添加注释并编写高效代码

我已经无数次向开发者同行宣传为代码作注解的重要性。但最近我发现一个奇怪的事实：许多开发者并未考虑用JavaScript或HTML编写代码，所以他们也很少为这类代码作注解。用书面文件或代码注释彻底为JavaScript代码作注解，不仅对您自己有帮助，对将来应用这些代码的开发者也有指导作用。

用注释给代码作注解

书面文件当然不错，但我还是喜欢用代码编写的文件——以防出现书面文件遗失的情况。给代码作注解是个良好的习惯，在编写代码时也很容易做到。一些语言，如Java和C#提供了特定的注解功能。

JavaScript并不具备这种功能，但您可以方便地用注释作注解。在JavaScript中有两种进行注释的方法：

• /*（开始注释）与*/（结束注释）字符组合允许您增加多行注释，因此在注释开始与结束指示符之间的所有代码不被执行。
• 单行注释放在两个反斜杠字符（//）之间。两个反斜杠间的所有文本都被忽略。这些注释可以自成一行，也可放在JavaScript代码的后面。

列表A中的HTML样本代码包含了应用这两种技巧的JavaScript代码。这是一个简单的HTML页面，在页面加载时显示一个信息框，但其中包含许多注解。可能您宁愿开发别的技巧，但这其中的一些技巧可以专门用来为代码作注解。毕竟，不必对优秀的代码进行创新，但使代码高效、方便地执行，且易于维护就很有必要。

在给代码作注解时，哪些地方可以增加大量信息也需要一定的技巧。毕竟，并不是每行代码都需要注解。以下是给JavaScript代码作注解的几点指导：

• 给所有的函数作注解，包括函数的功能，参数与返回值（如果存在）说明。我的简单实例中包含了上述信息。我喜欢说明作者和日期，但您也可以在页面文件中进行说明。（因为整个页面的作者和日期可能相同），但这属于开发者和组织的喜好。
• 对晦涩或复杂的代码进行注解，以帮助将来的开发者了解它的作用。
• 如果代码发生了改变，要用一行注释进行详细说明：由谁，为什么进行改变。这有助于调试并追踪开发者。

这些并不是强制性的指导，不同组织的指导方针也各不相同；关键在于保持一致，使所有代码都遵循同一套准则。

编写高效代码

注解代码只是缓解代码维护压力的一个方面。您可以应用下面的另外一些技巧帮助开发者同行提高代码的可读性：

• 正确缩进
• 显而易见的变量与方法名称
• 脚本块的括号位置保持一致

虽然TechRepublic网站的显示细节在本文的样本代码中取消了行缩进，但您应该根据开发者和/或组织的喜好缩进代码。另外，您会注意到实例中的变量与函数名称都相当明确，开发者不必查看相应的注释就能够确定代码的功能。

列表中的最后一项与包含代码块的大括号（）的位置有关。一些组织喜欢在代码之前使用括号，其它组织则在第一行代码之后应用括号。样本代码使用了前一种方法，但函数可以使用列表B中代码所说明的其它技巧。

HTML注释

除JavaScript注释外，您还可以用HTML格式的注释在HTML代码中添加注释或注解。HTML注释使用下面的格式：

<!-- This is an HTML comment -->

样本代码的页面顶部是一行HTML注释。注释的位置依项目而定，但可以用它们来防止页面的一些部分进入加载/执行过程，以帮助进行调试。

帮助其他人

编写易读代码是一个每天都要进行的连续性过程。毕竟，多数开发者讨厌注解，不是人人都愿意在项目完成后再倒过头来给代码添加注释。您可以加入注释，使代码的格式保持一致，为将来进行维护或修改的开发者提供方便。

Tony Patton拥有丰富的Java、VB、Lotus及XML方面的知识，是一个专业的应用程序开发人员。

责任编辑：张琎

查看本文的国际来源