关闭

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

标签: 读书笔记javascript
185人阅读 评论(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网站的观点或立场

《编写可维护的JavaScript》读书笔记(2)---注释

注释(Comments) Opening a file without any comments may seem like a fun adventure, but when there are...
  • Suejia
  • Suejia
  • 2017-05-31 11:10
  • 218

编写可维护的javascript读书笔记

换行问题: 在运算符后换行,下一行会增加两个层级的缩进。注释: 注释要有缩进 注释要和代码有空行 多行注释可以采用:/* * 注释一行 * 注释一行 * /显而易见的代码不要加...
  • tingyugetc11
  • tingyugetc11
  • 2017-04-01 19:37
  • 141

读书笔记:编写可维护的javascript

#. 使用for-in循环的时候,要使用hasOwnProperty方法进行过滤,除非你想查找原型链上的继承属性 #. 不应当使用for-in循环进行数组遍历,而只应该对object的属性进行遍历 #...
  • Robinsone
  • Robinsone
  • 2015-06-17 14:30
  • 867

《编写可维护的JavaScript》- 读书笔记

引用这是我刷完的第一本书。万事开头难,总算是在2017年02月09日开了一个好头。这篇总结是为了记录在读这本书的过程中所遇到的好的知识点和思想,以及我在实际工作中结合作者的想法所做的一些实践和读书的收...
  • wsy526659583
  • wsy526659583
  • 2017-04-01 21:52
  • 177

编写可维护的javascript(一):基本的格式化

一 基本的格式化 语句结尾 依赖于分析器的自动分号插入(ASI)机制,javascript代码省略分号是可以正常工作。ASI会自动寻找出代码中应当使用分号但实际没有分号的位置,并插入分号。在...
  • mangoyiy
  • mangoyiy
  • 2017-07-25 17:34
  • 110

编写可维护的JavaScript读书笔记(1)

编程风格 基本的格式化 1.当一行的长度达到了单行最大字符数限制时,需要将一行拆为两行,第二行要有两个层级的缩进 2.null的使用 应用场景: (1) 用来初始化一个变量,这个变量可能赋值为一个对象...
  • Ghostiostream
  • Ghostiostream
  • 2013-12-30 11:44
  • 376

编写可维护的JavaScript读书笔记(2)

编程实践 1.将JavaScript从CSS中抽离 要避免使用CSS表达式 2.将CSS从JavaScript中抽离 最好使用JavaScript操作CSS的classname,而不要直接更改....
  • Ghostiostream
  • Ghostiostream
  • 2013-12-30 15:10
  • 415

JavaScript代码不好读,不好维护?你需要改变写代码的习惯

良好的编码习惯,这是每个程序员应具备的最基本素质。无论是前端程序员还是后端程序员,都要遵循基本的规范,减少因代码混乱而造成难以维护的局面。要做到不管有多少人共同参与同一个项目,一定要确保每一行代码都像...
  • u013794666
  • u013794666
  • 2015-03-18 18:04
  • 520

《编写可维护的JavaScript》读书笔记——3.语句和表达式

所有的块语句都应当使用花括号,包括: if for while do…while… try…catch…finally 3.1 花括号的对齐方式 风格:左花括号放置在块语句中第一句代码的末尾。 示...
  • hj08053127
  • hj08053127
  • 2016-08-31 14:24
  • 166

《编写可维护的JavaScript》读书笔记——1.基本的格式化

《编写可维护的JavaScript》读书笔记——1.基本的格式化 缩进层级 使用制表符进行缩进,每一个缩进层级都用单独的制表符(tab character)表示。一个缩进层级是一个制表符,两个缩进...
  • hj08053127
  • hj08053127
  • 2016-08-23 16:34
  • 186
    个人资料
    • 访问:22977次
    • 积分:481
    • 等级:
    • 排名:千里之外
    • 原创:24篇
    • 转载:1篇
    • 译文:1篇
    • 评论:11条
    最新评论