二、注释

标签：

2.1 单行注释

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

    单行注释有三种写法：

    （1）独占一行的注释，用来解释下一行代码。这行注释之前总是有一个空行，且缩进层级和下一行保持一致。

    （2）在代码行的尾部的注释。代码结束到注释之间至少有一个缩进。注释（包括之前的代码部分）不应当超过单行最大字符数限制，如果超过了，就将这条注释放置于当前代码行的上方。

    （3）被注释掉的大段代码（很多编辑器都可以批量注释掉多行代码）。

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

// 好的写法
if (condition) {

    // 如果代码执行到这里，则表明通过了所有安全性检查
    doSomething();
}

// 不好的写法：注释之前没有空行
if (condition) {
    // 如果代码执行到这里，则表明通过了所有安全性检查
    doSomething();
}

// 不好的写法：错误的缩进
if (condition) {
// 如果代码执行到这里，则表明通过了所有安全性检查
    doSomething();
}

// 好的写法
var result = something + somethingElse; //somethingElse不应当取值为null

// 不好的写法：代码和注释之间没有间隔
var result = something + somethingElse;//somethingElse不应当取值为null

// 好的写法
// if (condition) {
//     doSomething();
// }

// 不好的写法：这里应当用多行注释
// 接下来的这段代码非常难，那么，我来详细解释一下
// 这段代码的作用是首先判断条件是否为真
// 只有当为真时才会执行
// 多个函数计算出来的，在整个会话生命周期内
// 这个值是可以修改的
if (condition) {
    // 如果代码执行到这里，则表明通过了所有安全性检查
    doSomething();
}

2.2 多行注释

    多行注释可以包裹跨行文本。它以/*开始，以*/结束。

    Java风格的注释至少包含三行：第一行是/*，第二行是以*开始且和上一行的*保持左对齐，最后一行是*/。

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

// 好的写法
if (condition) {

    /*
     * 如果这行代码执行到这里
     * 说明通过了所有安全性检测
     */
    doSomething();
}

// 不好的写法：注释之前没有空行
if (condition) {
    /*
     * 如果这行代码执行到这里
     * 说明通过了所有安全性检测
     */
    doSomething();
}

// 不好的写法：星号后面没有空格
if (condition) {

    /*
     *如果这行代码执行到这里
     *说明通过了所有安全性检测
     */
    doSomething();
}

// 不好的写法：错误的缩进
if (condition) {

  /*
   *如果这行代码执行到这里
   *说明通过了所有安全性检测
   */
    doSomething();
}

// 不好的写法：代码尾部注释不要用多行注释风格
var result = something + somethingElse; /*somethingElse不应当取值为null*/

2.3 使用注释

    一种通行的指导原则是，当代码不够清晰时添加注释，而当代码很明了时不应当添加注释。比如下面的例子，注释是画蛇添足。

    // 初始化count

    var count = 10;

    因为代码中初始化count的操作是显而易见的。注释并没有提供其他有价值的信息。换个角度讲，如果这个值10具有一些特殊的含义，而且无法直接从代码中看出来，就没有必要添加注释了。

    // 改变这个值可能会让它变成青蛙

    var count = 10;

    如果没有添加注释，你修改了count的值，变成了青蛙，就会让人困惑不解。

    因此，添加注释的一个原则是，在需要让代码变得更清晰时添加注释。

2.3.1 难于理解的代码

    难于理解的代码通常都应当加注释。根据代码的用途，你可以进行单行注释，多行注释，或者混合使用这两种注释。关键是让其他人更容易读懂这段代码。

2.3.2 可能被误认为错误的代码

    另一个适合添加注释的好时机是当代码看上去有错误时。在团队开发中，总是会有好心的开发者在编辑代码时发现他人的错误代码，就立即将它修复。有时这段代码并不是错误的源头，所以“修复”这个错误往往会制造其他错误，因为本次修改应当是可追踪的。当你写的代码有可能会被别的开发者认为有错误时，则需要添加注释。

2.3.3 浏览器特性hack

    JavaScript程序员常常会编写一些低效的、不雅的、彻头彻尾的肮脏代码，用来让低级浏览器正常工作。实际上这种情形是一种特殊的“可能被误认为是错误的代码”：这种不明显的做浏览器特性Hack的代码可能隐含一些错误。

2.4 文档注释

    JavaDoc文档格式：多行注释以单斜线加双星号（/**）开始，接下来是描述信息，其中使用@符号来表示一个或多个属性。

/**
 * 这是一个计算整数和的方法
 * @method addNumber
 * @param {Number} 整数
 * @return {Number} 一个计算后的结果
 */
 var addNumber = function (x, y) {
     return x + y;
 }

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

    （1）所有的方法

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

    （2）所有的构造函数

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

    （3）所有包含文档化方法的对象

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

        当然，注释的格式和用法最终还是由你所选择的文档生成工具决定的。

二、注释

标签：

原文地址：http://www.cnblogs.com/huangguaxiaocai/p/5074733.html