百度前端代码规范

1 .

2 . 目 录 致谢 README Javascript编码规范 Javascript编码规范 - ESNext补充篇 HTML编码规范 CSS编码规范 Less编码规范 E-JSON数据传输标准 模块和加载器规范 包结构规范 项目目录结构规范 图表库标准 react编码规范 本文档使用 书栈(BookStack.CN) 构建 - 2 - 

3 .致谢 致谢 当前文档 《百度前端代码规范》 由 进击的皇虫 使用 书栈(BookStack.CN) 进行构建，生成 于 2018-07-04。 书栈(BookStack.CN) 仅提供文档编写、整理、归类等功能，以及对文档内容的生成和导出工 具。 文档内容由网友们编写和整理，书栈(BookStack.CN) 难以确认文档内容知识点是否错漏。如果 您在阅读文档获取知识的时候，发现文档内容有不恰当的地方，请向我们反馈，让我们共同携手，将知 识准确、高效且有效地传递给每一个人。 同时，如果您在日常工作、生活和学习中遇到有价值有营养的知识文档，欢迎分享到 书栈 (BookStack.CN) ，为知识的传承献上您的一份力量！ 如果当前文档生成时间太久，请到 书栈(BookStack.CN) 获取最新的文档，以跟上知识更新换 代的步伐。 文档地址：http://www.bookstack.cn/books/ecomfe-spec 书栈官网：http://www.bookstack.cn 书栈开源：https://github.com/TruthHun 分享，让知识传承更久远！ 感谢知识的创造者，感谢知识的分享者，也感谢每一位阅读到此处的 读者，因为我们都将成为知识的传承者。 本文档使用 书栈(BookStack.CN) 构建 - 3 - 

4 .README README This repository contains the specifications. Javascript编码规范 [1.3] Javascript编码规范 - ESNext补充篇 [draft] HTML编码规范 [1.2] CSS编码规范 [1.2] Less编码规范 [1.1] E-JSON数据传输标准 [1.0] 模块和加载器规范 [1.1] 包结构规范 [1.1] 项目目录结构规范 [1.1] 图表库标准 [1.0] react编码规范 [draft] Lint and fix tool：FECS 来源(书栈小编注) https://github.com/ecomfe/spec 本文档使用 书栈(BookStack.CN) 构建 - 4 - 

5 .Javascript编码规范 Javascript编码规范 JavaScript编码规范 1 前言 JavaScript 在百度一直有着广泛的应用，特别是在浏览器端的行为管理。本文档的目标是使 JavaScript 代码风格保持一致，容易被理解和被维护。 虽然本文档是针对 JavaScript 设计的，但是在使用各种 JavaScript 的预编译语言时(如 TypeScript 等)时，适用的部分也应尽量遵循本文档的约定。 2 代码风格 2.1 文件 [建议] JavaScript 文件使用无 BOM 的 UTF-8 编码。 解释： UTF-8 编码具有更广泛的适应性。BOM 在使用程序或工具处理文件时可能造成不必要的干扰。 [建议] 在文件结尾处，保留一个空行。 2.2 结构 2.2.1 缩进 [强制] 使用 4 个空格做为一个缩进层级，不允许使用 2 个空格 或 tab 字符。 [强制] switch 下的 case 和 default 必须增加一个缩进层级。 示例： 1. // good 2. switch (variable) { 3. 4. case '1': 5. // do... 6. break; 7. 本文档使用 书栈(BookStack.CN) 构建 - 5 - 

6 .Javascript编码规范 8. case '2': 9. // do... 10. break; 11. 12. default: 13. // do... 14. 15. } 16. 17. // bad 18. switch (variable) { 19. 20. case '1': 21. // do... 22. break; 23. 24. case '2': 25. // do... 26. break; 27. 28. default: 29. // do... 30. 31. } 2.2.2 空格 [强制] 二元运算符两侧必须有一个空格，一元运算符与操作对象之间不允许有空格。 示例： 1. var a = !arr.length; 2. a++; 3. a = b + c; [强制] 用作代码块起始的左花括号 { 前必须有一个空格。 示例： 1. // good 2. if (condition) { 3. } 4. 本文档使用 书栈(BookStack.CN) 构建 - 6 - 

7 .Javascript编码规范 5. while (condition) { 6. } 7. 8. function funcName() { 9. } 10. 11. // bad 12. if (condition){ 13. } 14. 15. while (condition){ 16. } 17. 18. function funcName(){ 19. } [强制] if / else / for / while / function / switch / do / try / catch / finally 关键 字后，必须有一个空格。 示例： 1. // good 2. if (condition) { 3. } 4. 5. while (condition) { 6. } 7. 8. (function () { 9. })(); 10. 11. // bad 12. if(condition) { 13. } 14. 15. while(condition) { 16. } 17. 18. (function() { 19. })(); [强制] 在对象创建时，属性中的 : 之后必须有空格， : 之前不允许有空格。 本文档使用 书栈(BookStack.CN) 构建 - 7 - 

8 .Javascript编码规范 示例： 1. // good 2. var obj = { 3. a: 1, 4. b: 2, 5. c: 3 6. }; 7. 8. // bad 9. var obj = { 10. a : 1, 11. b:2, 12. c :3 13. }; [强制] 函数声明、具名函数表达式、函数调用中，函数名和 ( 之间不允许有空格。 示例： 1. // good 2. function funcName() { 3. } 4. 5. var funcName = function funcName() { 6. }; 7. 8. funcName(); 9. 10. // bad 11. function funcName () { 12. } 13. 14. var funcName = function funcName () { 15. }; 16. 17. funcName (); [强制] , 和 ; 前不允许有空格。如果不位于行尾， , 和 ; 后必须跟一个空格。 示例： 1. // good 本文档使用 书栈(BookStack.CN) 构建 - 8 - 

9 .Javascript编码规范 2. callFunc(a, b); 3. 4. // bad 5. callFunc(a , b) ; [强制] 在函数调用、函数声明、括号表达式、属性访问、 if / for / while / switch / catch 等语句中， () 和 [] 内紧贴括号部分不允许有空格。 示例： 1. // good 2. 3. callFunc(param1, param2, param3); 4. 5. save(this.list[this.indexes[i]]); 6. 7. needIncream && (variable += increament); 8. 9. if (num > list.length) { 10. } 11. 12. while (len--) { 13. } 14. 15. 16. // bad 17. 18. callFunc( param1, param2, param3 ); 19. 20. save( this.list[ this.indexes[ i ] ] ); 21. 22. needIncreament && ( variable += increament ); 23. 24. if ( num > list.length ) { 25. } 26. 27. while ( len-- ) { 28. } [强制] 单行声明的数组与对象，如果包含元素， {} 和 [] 内紧贴括号部分不允许包含空格。 解释： 本文档使用 书栈(BookStack.CN) 构建 - 9 - 

10 .Javascript编码规范 声明包含元素的数组与对象，只有当内部元素的形式较为简单时，才允许写在一行。元素复杂的情况， 还是应该换行书写。 示例： 1. // good 2. var arr1 = []; 3. var arr2 = [1, 2, 3]; 4. var obj1 = {}; 5. var obj2 = {name: 'obj'}; 6. var obj3 = { 7. name: 'obj', 8. age: 20, 9. sex: 1 10. }; 11. 12. // bad 13. var arr1 = [ ]; 14. var arr2 = [ 1, 2, 3 ]; 15. var obj1 = { }; 16. var obj2 = { name: 'obj' }; 17. var obj3 = {name: 'obj', age: 20, sex: 1}; [强制] 行尾不得有多余的空格。 2.2.3 换行 [强制] 每个独立语句结束后必须换行。 [强制] 每行不得超过 120 个字符。 解释： 超长的不可分割的代码允许例外，比如复杂的正则表达式。长字符串不在例外之列。 [强制] 运算符处换行时，运算符必须在新行的行首。 示例： 1. // good 2. if (user.isAuthenticated() 3. && user.isInRole('admin') 4. && user.hasAuthority('add-admin') 5. || user.hasAuthority('delete-admin') 6. ) { 本文档使用 书栈(BookStack.CN) 构建 - 10 - 

11 .Javascript编码规范 7. // Code 8. } 9. 10. var result = number1 + number2 + number3 11. + number4 + number5; 12. 13. 14. // bad 15. if (user.isAuthenticated() && 16. user.isInRole('admin') && 17. user.hasAuthority('add-admin') || 18. user.hasAuthority('delete-admin')) { 19. // Code 20. } 21. 22. var result = number1 + number2 + number3 + 23. number4 + number5; [强制] 在函数声明、函数表达式、函数调用、对象创建、数组创建、 for 语句等场景中，不允许在 , 或 ; 前换行。 示例： 1. // good 2. var obj = { 3. a: 1, 4. b: 2, 5. c: 3 6. }; 7. 8. foo( 9. aVeryVeryLongArgument, 10. anotherVeryLongArgument, 11. callback 12. ); 13. 14. 15. // bad 16. var obj = { 17. a: 1 18. , b: 2 19. , c: 3 20. }; 本文档使用 书栈(BookStack.CN) 构建 - 11 - 

12 .Javascript编码规范 21. 22. foo( 23. aVeryVeryLongArgument 24. , anotherVeryLongArgument 25. , callback 26. ); [建议] 不同行为或逻辑的语句集，使用空行隔开，更易阅读。 示例： 1. // 仅为按逻辑换行的示例，不代表setStyle的最优实现 2. function setStyle(element, property, value) { 3. if (element == null) { 4. return; 5. } 6. 7. element.style[property] = value; 8. } [建议] 在语句的行长度超过 120 时，根据逻辑条件合理缩进。 示例： 1. // 较复杂的逻辑条件组合，将每个条件独立一行，逻辑运算符放置在行首进行分隔，或将部分逻辑按逻辑 组合进行分隔。 2. // 建议最终将右括号 ) 与左大括号 { 放在独立一行，保证与 `if` 内语句块能容易视觉辨识。 3. if (user.isAuthenticated() 4. && user.isInRole('admin') 5. && user.hasAuthority('add-admin') 6. || user.hasAuthority('delete-admin') 7. ) { 8. // Code 9. } 10. 11. // 按一定长度截断字符串，并使用 + 运算符进行连接。 12. // 分隔字符串尽量按语义进行，如不要在一个完整的名词中间断开。 13. // 特别的，对于 HTML 片段的拼接，通过缩进，保持和 HTML 相同的结构。 14. var html = '' // 此处用一个空字符串，以便整个 HTML 片段都在新行严格对齐 15. + '<article>' 16. + '<h1>Title here</h1>' 17. + '<p>This is a paragraph</p>' 18. + '<footer>Complete</footer>' 本文档使用 书栈(BookStack.CN) 构建 - 12 - 

13 .Javascript编码规范 19. + '</article>'; 20. 21. // 也可使用数组来进行拼接，相对 `+` 更容易调整缩进。 22. var html = [ 23. '<article>', 24. '<h1>Title here</h1>', 25. '<p>This is a paragraph</p>', 26. '<footer>Complete</footer>', 27. '</article>' 28. ]; 29. html = html.join(''); 30. 31. // 当参数过多时，将每个参数独立写在一行上，并将结束的右括号 ) 独立一行。 32. // 所有参数必须增加一个缩进。 33. foo( 34. aVeryVeryLongArgument, 35. anotherVeryLongArgument, 36. callback 37. ); 38. 39. // 也可以按逻辑对参数进行组合。 40. // 最经典的是 baidu.format 函数，调用时将参数分为“模板”和“数据”两块 41. baidu.format( 42. dateFormatTemplate, 43. year, month, date, hour, minute, second 44. ); 45. 46. // 当函数调用时，如果有一个或以上参数跨越多行，应当每一个参数独立一行。 47. // 这通常出现在匿名函数或者对象初始化等作为参数时，如 `setTimeout` 函数等。 48. setTimeout( 49. function () { 50. alert('hello'); 51. }, 52. 200 53. ); 54. 55. order.data.read( 56. 'id=' + me.model.id, 57. function (data) { 58. me.attchToModel(data.result); 59. callback(); 60. }, 本文档使用 书栈(BookStack.CN) 构建 - 13 - 

14 .Javascript编码规范 61. 300 62. ); 63. 64. // 链式调用较长时采用缩进进行调整。 65. $('#items') 66. .find('.selected') 67. .highlight() 68. .end(); 69. 70. // 三元运算符由3部分组成，因此其换行应当根据每个部分的长度不同，形成不同的情况。 71. var result = thisIsAVeryVeryLongCondition 72. ? resultA : resultB; 73. 74. var result = condition 75. ? thisIsAVeryVeryLongResult 76. : resultB; 77. 78. // 数组和对象初始化的混用，严格按照每个对象的 `{` 和结束 `}` 在独立一行的风格书写。 79. var array = [ 80. { 81. // ... 82. }, 83. { 84. // ... 85. } 86. ]; [建议] 对于 if...else... 、 try...catch...finally 等语句，推荐使用在 } 号后添加一 个换行 的风格，使代码层次结构更清晰，阅读性更好。 示例： 1. if (condition) { 2. // some statements; 3. } 4. else { 5. // some statements; 6. } 7. 8. try { 9. // some statements; 10. } 11. catch (ex) { 本文档使用 书栈(BookStack.CN) 构建 - 14 - 

15 .Javascript编码规范 12. // some statements; 13. } 2.2.4 语句 [强制] 不得省略语句结束的分号。 [强制] 在 if / else / for / do / while 语句中，即使只有一行，也不得省略块 {...} 。 示例： 1. // good 2. if (condition) { 3. callFunc(); 4. } 5. 6. // bad 7. if (condition) callFunc(); 8. if (condition) 9. callFunc(); [强制] 函数定义结束不允许添加分号。 示例： 1. // good 2. function funcName() { 3. } 4. 5. // bad 6. function funcName() { 7. }; 8. 9. // 如果是函数表达式，分号是不允许省略的。 10. var funcName = function () { 11. }; [强制] IIFE 必须在函数表达式外添加 ( ，非 IIFE 不得在函数表达式外添加 ( 。 解释： IIFE = Immediately-Invoked Function Expression. 额外的 ( 能够让代码在阅读的一开始就能判断函数是否立即被调用，进而明白接下来代码的用途。而 本文档使用 书栈(BookStack.CN) 构建 - 15 - 

16 .Javascript编码规范 不是一直拖到底部才恍然大悟。 示例： 1. // good 2. var task = (function () { 3. // Code 4. return result; 5. })(); 6. 7. var func = function () { 8. }; 9. 10. 11. // bad 12. var task = function () { 13. // Code 14. return result; 15. }(); 16. 17. var func = (function () { 18. }); 2.3 命名 [强制] 变量 使用 Camel命名法 。 示例： 1. var loadingModules = {}; [强制] 常量 使用 全部字母大写，单词间下划线分隔 的命名方式。 示例： 1. var HTML_ENTITY = {}; [强制] 函数 使用 Camel命名法 。 示例： 1. function stringFormat(source) { 2. } 本文档使用 书栈(BookStack.CN) 构建 - 16 - 

17 .Javascript编码规范 [强制] 函数的 参数 使用 Camel命名法 。 示例： 1. function hear(theBells) { 2. } [强制] 类 使用 Pascal命名法 。 示例： 1. function TextNode(options) { 2. } [强制] 类的 方法 / 属性 使用 Camel命名法 。 示例： 1. function TextNode(value, engine) { 2. this.value = value; 3. this.engine = engine; 4. } 5. 6. TextNode.prototype.clone = function () { 7. return this; 8. }; [强制] 枚举变量 使用 Pascal命名法 ， 枚举的属性 使用 全部字母大写，单词间下划线分隔 的命 名方式。 示例： 1. var TargetState = { 2. READING: 1, 3. READED: 2, 4. APPLIED: 3, 5. READY: 4 6. }; [强制] 命名空间 使用 Camel命名法 。 示例： 1. equipments.heavyWeapons = {}; 本文档使用 书栈(BookStack.CN) 构建 - 17 - 

18 .Javascript编码规范 [强制] 由多个单词组成的缩写词，在命名中，根据当前命名法和出现的位置，所有字母的大小写与首 字母的大小写保持一致。 示例： 1. function XMLParser() { 2. } 3. 4. function insertHTML(element, html) { 5. } 6. 7. var httpRequest = new HTTPRequest(); [强制] 类名 使用 名词 。 示例： 1. function Engine(options) { 2. } [建议] 函数名 使用 动宾短语 。 示例： 1. function getStyle(element) { 2. } [建议] boolean 类型的变量使用 is 或 has 开头。 示例： 1. var isReady = false; 2. var hasMoreCommands = false; [建议] Promise对象 用 动宾短语的进行时 表达。 示例： 1. var loadingData = ajax.get('url'); 2. loadingData.then(callback); 2.4 注释 本文档使用 书栈(BookStack.CN) 构建 - 18 - 

19 .Javascript编码规范 2.4.1 单行注释 [强制] 必须独占一行。 // 后跟一个空格，缩进与下一行被注释说明的代码一致。 2.4.2 多行注释 [建议] 避免使用 /*...*/ 这样的多行注释。有多行注释内容时，使用多个单行注释。 2.4.3 文档化注释 [强制] 为了便于代码阅读和自文档化，以下内容必须包含以 /**...*/ 形式的块注释中。 解释： 1. 文件 2. namespace 3. 类 4. 函数或方法 5. 类属性 6. 事件 7. 全局变量 8. 常量 9. AMD 模块 [强制] 文档注释前必须空一行。 [建议] 自文档化的文档说明 what，而不是 how。 2.4.4 类型定义 [强制] 类型定义都是以 { 开始, 以 } 结束。 解释： 常用类型如：{string}, {number}, {boolean}, {Object}, {Function}, {RegExp}, {Array}, {Date}。 类型不仅局限于内置的类型，也可以是自定义的类型。比如定义了一个类 Developer，就可以使用它 来定义一个参数和返回值的类型。 [强制] 对于基本类型 {string}, {number}, {boolean}，首字母必须小写。 类型定义 语法示例 解释 String {string} — Number {number} — Boolean {boolean} — 本文档使用 书栈(BookStack.CN) 构建 - 19 - 

20 .Javascript编码规范 Object {Object} — Function {Function} — RegExp {RegExp} — Array {Array} — Date {Date} — 单一类型集合 {Array.<string>} string 类型的数组 可能是 number 类型, 也可能是 boolean 多类型 {(number｜boolean)} 类型 允许为null {?number} 可能是 number, 也可能是 null 不允许为null {!Object} Object 类型, 但不是 null Function类型 {function(number, boolean)} 函数, 形参类型 Function带返 {function(number, 函数, 形参, 返回值类型 回值 boolean):string} Promise.<resolveType, Promise，成功返回的数据类型，失败返回的 Promise rejectType> 错误类型 参数可选 @param {string=} name 可选参数, =为类型后缀 可变参数 @param {…number} args 变长参数, …为类型前缀 任意类型 {*} 任意类型 可选任意类型 @param {*=} name 可选参数，类型不限 可变任意类型 @param {…*} args 变长参数，类型不限 2.4.5 文件注释 [强制] 文件顶部必须包含文件注释，用 @file 标识文件说明。 示例： 1. /** 2. * @file Describe the file 3. */ [建议] 文件注释中可以用 @author 标识开发者信息。 解释： 开发者信息能够体现开发人员对文件的贡献，并且能够让遇到问题或希望了解相关信息的人找到维护 人。通常情况文件在被创建时标识的是创建者。随着项目的进展，越来越多的人加入，参与这个文件的 开发，新的作者应该被加入 @author 标识。 @author 标识具有多人时，原则是按照 责任 进行排序。通常的说就是如果有问题，就是找第 一个人应该比找第二个人有效。比如文件的创建者由于各种原因，模块移交给了其他人或其他团队，后 来因为新增需求，其他人在新增代码时，添加 @author 标识应该把自己的名字添加在创建人的前 本文档使用 书栈(BookStack.CN) 构建 - 20 - 

21 .Javascript编码规范 面。 @author 中的名字不允许被删除。任何劳动成果都应该被尊重。 业务项目中，一个文件可能被多人频繁修改，并且每个人的维护时间都可能不会很长，不建议为文件增 加 @author 标识。通过版本控制系统追踪变更，按业务逻辑单元确定模块的维护责任人，通过文 档与wiki跟踪和查询，是更好的责任管理方式。 对于业务逻辑无关的技术型基础项目，特别是开源的公共项目，应使用 @author 标识。 示例： 1. /** 2. * @file Describe the file 3. * @author author-name(mail-name@domain.com) 4. * author-name2(mail-name2@domain.com) 5. */ 2.4.6 命名空间注释 [建议] 命名空间使用 @namespace 标识。 示例： 1. /** 2. * @namespace 3. */ 4. var util = {}; 2.4.7 类注释 [建议] 使用 @class 标记类或构造函数。 解释： 对于使用对象 constructor 属性来定义的构造函数，可以使用 @constructor 来标记。 示例： 1. /** 2. * 描述 3. * 4. * @class 5. */ 本文档使用 书栈(BookStack.CN) 构建 - 21 - 

22 .Javascript编码规范 6. function Developer() { 7. // constructor body 8. } [建议] 使用 @extends 标记类的继承信息。 示例： 1. /** 2. * 描述 3. * 4. * @class 5. * @extends Developer 6. */ 7. function Fronteer() { 8. Developer.call(this); 9. // constructor body 10. } 11. util.inherits(Fronteer, Developer); [强制] 使用包装方式扩展类成员时， 必须通过 @lends 进行重新指向。 解释： 没有 @lends 标记将无法为该类生成包含扩展类成员的文档。 示例： 1. /** 2. * 类描述 3. * 4. * @class 5. * @extends Developer 6. */ 7. function Fronteer() { 8. Developer.call(this); 9. // constructor body 10. } 11. 12. util.extend( 13. Fronteer.prototype, 14. /** @lends Fronteer.prototype */{ 15. getLevel: function () { 本文档使用 书栈(BookStack.CN) 构建 - 22 - 

23 .Javascript编码规范 16. // TODO 17. } 18. } 19. ); [强制] 类的属性或方法等成员信息不是 public 的，应使用 @protected 或 @private 标 识可访问性。 解释： 生成的文档中将有可访问性的标记，避免用户直接使用非 public 的属性或方法。 示例： 1. /** 2. * 类描述 3. * 4. * @class 5. * @extends Developer 6. */ 7. var Fronteer = function () { 8. Developer.call(this); 9. 10. /** 11. * 属性描述 12. * 13. * @type {string} 14. * @private 15. */ 16. this.level = 'T12'; 17. 18. // constructor body 19. }; 20. util.inherits(Fronteer, Developer); 21. 22. /** 23. * 方法描述 24. * 25. * @private 26. * @return {string} 返回值描述 27. */ 28. Fronteer.prototype.getLevel = function () { 29. }; 本文档使用 书栈(BookStack.CN) 构建 - 23 - 

24 .Javascript编码规范 2.4.8 函数/方法注释 [强制] 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。 解释： 当 return 关键字仅作退出函数/方法使用时，无须对返回值作注释标识。 [强制] 参数和返回值注释必须包含类型信息，且不允许省略参数的说明。 [建议] 当函数是内部函数，外部不可访问时，可以使用 @inner 标识。 示例： 1. /** 2. * 函数描述 3. * 4. * @param {string} p1 参数1的说明 5. * @param {string} p2 参数2的说明，比较长 6. * 那就换行了. 7. * @param {number=} p3 参数3的说明（可选） 8. * @return {Object} 返回值描述 9. */ 10. function foo(p1, p2, p3) { 11. var p3 = p3 || 10; 12. return { 13. p1: p1, 14. p2: p2, 15. p3: p3 16. }; 17. } [强制] 对 Object 中各项的描述， 必须使用 @param 标识。 示例： 1. /** 2. * 函数描述 3. * 4. * @param {Object} option 参数描述 5. * @param {string} option.url option项描述 6. * @param {string=} option.method option项描述，可选参数 7. */ 8. function foo(option) { 9. // TODO 本文档使用 书栈(BookStack.CN) 构建 - 24 - 

25 .Javascript编码规范 10. } [建议] 重写父类方法时， 应当添加 @override 标识。如果重写的形参个数、类型、顺序和返回 值类型均未发生变化，可省略 @param 、 @return ，仅用 @override 标识，否则仍应作完整注 释。 解释： 简而言之，当子类重写的方法能直接套用父类的方法注释时可省略对参数与返回值的注释。 2.4.9 事件注释 [强制] 必须使用 @event 标识事件，事件参数的标识与方法描述的参数标识相同。 示例： 1. /** 2. * 值变更时触发 3. * 4. * @event Select#change 5. * @param {Object} e e描述 6. * @param {string} e.before before描述 7. * @param {string} e.after after描述 8. */ 9. this.fire( 10. 'change', 11. { 12. before: 'foo', 13. after: 'bar' 14. } 15. ); [强制] 在会广播事件的函数前使用 @fires 标识广播的事件，在广播事件代码前使用 @event 标识事件。 [建议] 对于事件对象的注释，使用 @param 标识，生成文档时可读性更好。 示例： 1. /** 2. * 点击处理 3. * 4. * @fires Select#change 5. * @private 6. */ 本文档使用 书栈(BookStack.CN) 构建 - 25 - 

26 .Javascript编码规范 7. Select.prototype.clickHandler = function () { 8. 9. /** 10. * 值变更时触发 11. * 12. * @event Select#change 13. * @param {Object} e e描述 14. * @param {string} e.before before描述 15. * @param {string} e.after after描述 16. */ 17. this.fire( 18. 'change', 19. { 20. before: 'foo', 21. after: 'bar' 22. } 23. ); 24. }; 2.4.10 常量注释 [强制] 常量必须使用 @const 标记，并包含说明和类型信息。 示例： 1. /** 2. * 常量说明 3. * 4. * @const 5. * @type {string} 6. */ 7. var REQUEST_URL = 'myurl.do'; 2.4.11 复杂类型注释 [建议] 对于类型未定义的复杂结构的注释，可以使用 @typedef 标识来定义。 示例： 1. // `namespaceA~` 可以换成其它 namepaths 前缀，目的是为了生成文档中能显示 `@typedef` 定 义的类型和链接。 2. /** 3. * 服务器 本文档使用 书栈(BookStack.CN) 构建 - 26 - 

27 .Javascript编码规范 4. * 5. * @typedef {Object} namespaceA~Server 6. * @property {string} host 主机 7. * @property {number} port 端口 8. */ 9. 10. /** 11. * 服务器列表 12. * 13. * @type {Array.<namespaceA~Server>} 14. */ 15. var servers = [ 16. { 17. host: '1.2.3.4', 18. port: 8080 19. }, 20. { 21. host: '1.2.3.5', 22. port: 8081 23. } 24. ]; 2.4.12 AMD 模块注释 [强制] AMD 模块使用 @module 或 @exports 标识。 解释： @exports 与 @module 都可以用来标识模块，区别在于 @module 可以省略模块名称。而只使用 @exports 时在 namepaths 中可以省略 module: 前缀。 示例： 1. define( 2. function (require) { 3. 4. /** 5. * foo description 6. * 7. * @exports Foo 8. */ 9. var foo = { 10. // TODO 本文档使用 书栈(BookStack.CN) 构建 - 27 - 

28 .Javascript编码规范 11. }; 12. 13. /** 14. * baz description 15. * 16. * @return {boolean} return description 17. */ 18. foo.baz = function () { 19. // TODO 20. }; 21. 22. return foo; 23. 24. } 25. ); 也可以在 exports 变量前使用 @module 标识： 1. define( 2. function (require) { 3. 4. /** 5. * module description. 6. * 7. * @module foo 8. */ 9. var exports = {}; 10. 11. 12. /** 13. * bar description 14. * 15. */ 16. exports.bar = function () { 17. // TODO 18. }; 19. 20. return exports; 21. } 22. ); 如果直接使用 factory 的 exports 参数，还可以： 本文档使用 书栈(BookStack.CN) 构建 - 28 - 

29 .Javascript编码规范 1. /** 2. * module description. 3. * 4. * @module 5. */ 6. define( 7. function (require, exports) { 8. 9. /** 10. * bar description 11. * 12. */ 13. exports.bar = function () { 14. // TODO 15. }; 16. return exports; 17. } 18. ); [强制] 对于已使用 @module 标识为 AMD模块 的引用，在 namepaths 中必须增加 module: 作前缀。 解释： namepaths 没有 module: 前缀时，生成的文档中将无法正确生成链接。 示例： 1. /** 2. * 点击处理 3. * 4. * @fires module:Select#change 5. * @private 6. */ 7. Select.prototype.clickHandler = function () { 8. /** 9. * 值变更时触发 10. * 11. * @event module:Select#change 12. * @param {Object} e e描述 13. * @param {string} e.before before描述 14. * @param {string} e.after after描述 15. */ 本文档使用 书栈(BookStack.CN) 构建 - 29 -