关闭

《编写可维护的JavaScript》读书笔记——2.注释

标签: 读书笔记javascript
153人阅读 评论(0) 收藏 举报
分类:

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

// 这是一句单行注释

使用方法:

  • 独占一行,解释下一行代码。注释前有一个空行,缩进层级和下一行代码保持一致。
  • 在代码行尾部的注释。代码结束到注释之间至少有一个缩进。注释加代码不应超过单行最大字符限制,如果超过,则这条注释放在代码行上方。
  • 批量注释掉的多行代码。

示例:

// 好的写法,注释前有一行空行,与下一行代码缩进保持一致
if (condition) {

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

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

// 好的写法,注释掉多行代码
// if (condition) {
//      doSomething();
//      thenDoSomethingElse();
// }

// 不好的写法,这里应当用多行注释
// 接下来这段代码非常难,我详细说一下
// 这段代码的作用是首先判断条件是否为真
// 为真时才执行
if (condition) {
    allow();
}

2.2 多行注释
多行注释可以跨行,以/*开始,以*/结束。采用Java风格多行注释。

/*
 * 另一段注释
 * 这段注释包含两段文本
 */

用法:多行注释总是在描述代码之前,注释和代码之间没有空行。注释之前有一个空行,缩进层级和描述代码一样。
示例:

// 好的写法,多行注释用Java风格,代码前有空行,缩进层级与描述代码一致。
if (condition) {

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

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

2.3 使用注释
使用原则:代码不清晰时添加注释,代码清晰时不添加注释。
使用场景:

  • 难以理解的代码
  • 可能被误认为错误的代码
  • 浏览器不兼容时,可能被认为是不好的代码

2.4 文档注释
格式(JavaDoc文档格式):多行注释以单斜线加双星号(/**)开始,以双星号加斜线(**/)结束,描述信息中,使用@符号来表示一个或多个属性。
示例:

/**
返回一个对象,这个对象包含被提供的所有属性。
后一个对象的属性会覆盖前一个对象的属性。
传入一个单独的对象,会创建一个它的浅拷贝(shallow copy)
如果需要深拷贝(deep copy),请使用'clone()'
@method merge
@param {Object} 被合并的一个或多个对象
@return {Object} 一个新的合并后的对象
**/
Y.merge = function () {
    var args = arguments,
        i    = 0,
        len  = args.length,
        result = {};
    for (; i < len; ++i){
        Y.mix(result, args[i], true);
    }
    return result;
}

使用文档注释时,确保对以下内容添加注释:

  • 所有的方法
    -对方法、期望的参数和可能的返回值添加注释
  • 所有的构造函数
    -对自定义类型和期望的参数添加注释
  • 所有包含文档化方法的对象
    -如果一个对象包含一个或多个附带文档注释的方法,这个对象也应当适当地针对文档生成工具添加注释
0
0

查看评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场
    个人资料
    • 访问:18892次
    • 积分:433
    • 等级:
    • 排名:千里之外
    • 原创:24篇
    • 转载:1篇
    • 译文:1篇
    • 评论:10条
    最新评论