4.1. 通用约定.pdf

4.1. 通⽤约定 通⽤约定 注释 原则 As short as possible （如⽆必要，勿增注释）：尽量提⾼代码本⾝的清晰性、可 读性。 As long as necessary （如有必要，尽量详尽）：合 的注释、空⾏排版等，可以 让代码更易阅读、更具美感。 单⾏注释 必须独占⼀⾏。// 后跟⼀个空格，缩进与下⼀⾏被注释说明的代码⼀致。 多⾏注释 避免使⽤ /*...*/ 这样的多⾏注释。有多⾏注释内容时，使⽤多个单⾏注释。 函数/⽅法注释 1. 函数/⽅法注释必须包含函数说明，有参数和返回值时必须使⽤注释标识。； 2. 参数和返回值注释必须包含类型信息和说明； 3. 当函数是内部函数，外部不可访问时，可以使⽤ @inner 标识； /** * 函数描述 * * @param {string} p1 参数1的说明 * @param {string} p2 参数2的说明，⽐较⻓ * 那就换⾏了. * @param {number=} p3 参数3的说明 （可选） * @return {Object} 返回值描述 */ function foo(p1, p2, p3) { ar p3 = p3 || 10; return { p1: p1, p2: p2, p3: p3 }; } ⽂件注释 ⽂件注释⽤于告诉不熟悉这段代码的读者这个⽂件中包含哪些东西。 应该提供⽂件的 ⼤体内容, 它的作者, 依赖关系和兼容性信息。如下: /** * @fileo er iew Description of file, its uses and information * about its dependencies. * @author user@ (Firstname Lastname) * Copyright 2009 Meizu Inc. All Rights Reser ed. */ 命名 变量, 使⽤ Camel 命名法。 ar loadingModules = {}; 私有属性、变量和⽅法以下划线 _ 开头。 ar _pri ateMethod = {}; 常量, 使⽤全部字母⼤写，单词间下划线分隔的命名⽅式。 ar HTML_ENTITY = {}; 1. 函数, 使⽤ Camel 命名法。 2. 函数的参数, 使⽤ Camel 命名法。 function stringFormat(source) {} function hear(theBells) {} 1. 类, 使⽤ Pascal 命名法 2. 类的 ⽅法 / 属性, 使⽤ Camel 命名法 function TextNode( alue, engine) { this. alue = alue; this.engine = engine; } TextNtotype.clone = function () { return this; }; 1. 枚 变量 使⽤ Pascal 命名法。 2. 枚 的属性， 使⽤全部字母⼤写，单词间下划线分隔的命名⽅式。 ar TargetState = { READING: 1, READED: 2, APPLIED: 3, READY : 4 }; 由多个单词组成的 缩写词，在命名中，根据当前命名法和出现的位置，所有字母的⼤ ⼩写与⾸字母的⼤⼩写保持⼀致。 function XMLParser() {} function insertHTML(element, html) {} ar httpRequest = new HTTPRequest(); 命名语法 类名，使⽤名词。 function Engine(options) {} 函数名，使⽤动宾短语。 function getStyle(element) {} boolean 类型的变量使⽤ is 或 has 开头。 ar isReady = false; ar hasMoreCommands = false; Promise 对象⽤动宾短语的进⾏时表达。 ar loadingData = ajax .get(url); loadingD