《编写可维护的JavaScript》——JavaScript编码规范(四)

注释

单行注释

单行注释以两个斜线开始,以行尾结束

单行注释有三种使用方法:

  • 独占一行的注释,用来解释下一行代码。这行注释前总是有一个空行,且缩进层级和下一行代码保持一致。
  • 在行尾的注释。代码结束到注释之间至少有一个缩进。注释(包括之前的代码部分)不应当超过单行最大字符数限制。如果超过了,就将这条注释放置于当前代码行的上方。
  • 被注释掉的大段代码(很多编辑器都可以批量注释掉多行代码)。

单行注释不应当以连续多行注释的形式出现,除非你注释掉一大段代码。只有当需要注释一段很长的文本时才使用多行注释

多行注释

多行注释可以包裹跨行文本。它以/*开始,以*/结束。多行注释不仅仅可以用来包裹跨行文本,这取决于你。

推荐的是java风格的多行注释。java风格的注释至少包含三行:第一行是/*,第二行是以*开始且和上一行的*保持左对齐,最后一行是*/。这种注释看起来像下面这样。

/*

* 另一段注释

* 这段注释包含两行文本

*/

通过在注释左侧注上星号,会让注释更清晰。有一些IDE(比如eclipse)会自动为你插入这些星号。星号后应有空格

多行注释总是出现在将要描述的代码段之前,注释和代码之间没有空行间隔。和单行注释一样,多行注释之前当有一个空行,且缩进层级和其要描述的代码保持一致。

使用注释

何时添加注释是程序员经常争论的一个话题。一种通行的指导原则是,当代码不够清晰时添加注释,而当代码很明了时不应当添加注释。

难于理解的代码通常都应当加注释。

可能被误认为错误的代码,需要添加注释

文档注释

从技术的角度来讲,文档注释并不是JavaScript的组成部分,但它们是一种普遍的实践。文档注释最流行的一种格式来源于JavaDoc文档格:多行注释以/**开始,接下来是描述信息,其中使用@符号来表示一个或多个属性。来看一段来自YUI的源码的例子。

/**
返回一个对象,这个对象包含被提供对象的所有属性。
后一个对象的属性会覆盖前一个对象的属性。
传入一个单独的对象,会创建一个它的浅拷贝(shallow copy)。
@method merge
@param {Object} 被合并的一个或多个对象
@return {Object} 一个新的合并后的对象
Y.merge = function(){

    //此处省略

    return result;
};

当使用文档注释时,你应当确保对如下内容添加注释。

  • 所有的方法

应当对方法、期望的参数和可能的返回值添加注释描述

  • 所有的构造函数

应当对自定义类型和期望的参数添加注释描述

  • 所有包含文档化方法的对象

如果一个对象包含一个或多个附带文档注释的方法,那么这个对象也应当适当地针对文档生成工具添加文档注释。

<!--

作者:纤锐
出处:http://www.cnblogs.com/beginner2014
本文版权归作者和博客园共有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文连接。谢谢合作。

-->

原文地址:https://www.cnblogs.com/beginner2014/p/5408884.html