本文档以
1 | Airbnb JavaScript Style Guide |
为基础,编写符合自己团队的编码规范;
统一了命名和注释两大痛点,就统一了80%的风格,所以我们重点拓展这两部分内容,主体部分请参考基础。
1
2
3
<span id="LC1" class="line" lang="javascript"> <span class="kd">let</span> <span class="nx">thisIsMyObject</span> <span class="o">=</span> <span class="p">{};</span></span>
<span id="LC2" class="line" lang="javascript"></span>
<span id="LC3" class="line" lang="javascript"> <span class="kd">function</span> <span class="nx">thisIsMyFunction</span><span class="p">()</span> <span class="p">{}</span></span>
1
2
3
4
5
6
7
8
9
10
11
12
13
<span id="LC1" class="line" lang="javascript"> <span class="kd">class</span> <span class="nx">User</span> <span class="p">{</span></span>
<span id="LC2" class="line" lang="javascript"> <span class="nx">name</span> <span class="o">=</span> <span class="s1">'xxx'</span><span class="p">;</span></span>
<span id="LC3" class="line" lang="javascript"> <span class="p">}</span></span>
<span id="LC4" class="line" lang="javascript"></span>
<span id="LC5" class="line" lang="javascript"> <span class="kd">function</span> <span class="nx">User</span><span class="p">(</span><span class="nx">options</span><span class="p">)</span> <span class="p">{</span></span>
<span id="LC6" class="line" lang="javascript"> <span class="k">this</span><span class="p">.</span><span class="nx">name</span> <span class="o">=</span> <span class="nx">options</span><span class="p">.</span><span class="nx">name</span><span class="p">;</span></span>
<span id="LC7" class="line" lang="javascript"> <span class="p">}</span></span>
<span id="LC8" class="line" lang="javascript"></span>
<span id="LC9" class="line" lang="javascript"> <span class="kd">const</span> <span class="nx">TargetState</span> <span class="o">=</span> <span class="p">{</span></span>
<span id="LC10" class="line" lang="javascript"> <span class="na">PENDING</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span></span>
<span id="LC11" class="line" lang="javascript"> <span class="na">SUCCESS</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span></span>
<span id="LC12" class="line" lang="javascript"> <span class="na">FAILURE</span><span class="p">:</span><span class="mi">3</span></span>
<span id="LC13" class="line" lang="javascript"> <span class="p">};</span></span>
1
2
3
4
5
6
7
<span id="LC1" class="line" lang="javascript"> <span class="kd">const</span> <span class="nx">HTML_ENTITY</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span></span>
<span id="LC2" class="line" lang="javascript"></span>
<span id="LC3" class="line" lang="javascript"> <span class="kd">const</span> <span class="nx">TargetState</span> <span class="o">=</span> <span class="p">{</span></span>
<span id="LC4" class="line" lang="javascript"> <span class="na">PENDING</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span></span>
<span id="LC5" class="line" lang="javascript"> <span class="na">SUCCESS</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span></span>
<span id="LC6" class="line" lang="javascript"> <span class="na">FAILURE</span><span class="p">:</span><span class="mi">3</span></span>
<span id="LC7" class="line" lang="javascript"> <span class="p">};</span></span>
1
2
3
4
5
<span id="LC1" class="line" lang="javascript"> <span class="kd">function</span> <span class="nx">XMLParser</span><span class="p">()</span> <span class="p">{}</span></span>
<span id="LC2" class="line" lang="javascript"></span>
<span id="LC3" class="line" lang="javascript"> <span class="kd">function</span> <span class="nx">insertHTML</span><span class="p">(</span><span class="nx">element</span><span class="p">,</span> <span class="nx">html</span><span class="p">)</span> <span class="p">{}</span></span>
<span id="LC4" class="line" lang="javascript"></span>
<span id="LC5" class="line" lang="javascript"> <span class="kd">var</span> <span class="nx">httpRequest</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">HTTPRequest</span><span class="p">();</span></span>
解释:JavaScript 并没有私有属性或私有方法的概念。虽然使用下划线是表示「私有」的一种共识,但实际上这些属性是完全公开的,它本身就是你公共接口的一部分。这种习惯或许会导致开发者错误的认为改动它不会造成破坏或者不需要去测试。长话短说:如果你想要某处为「私有」,它必须不能是显式提出的。
1
2
3
4
5
6
7
<span id="LC1" class="line" lang="javascript"> <span class="c1">// bad</span></span>
<span id="LC2" class="line" lang="javascript"> <span class="k">this</span><span class="p">.</span><span class="nx">__firstName__</span> <span class="o">=</span> <span class="s1">'Panda'</span><span class="p">;</span></span>
<span id="LC3" class="line" lang="javascript"> <span class="k">this</span><span class="p">.</span><span class="nx">firstName_</span> <span class="o">=</span> <span class="s1">'Panda'</span><span class="p">;</span></span>
<span id="LC4" class="line" lang="javascript"> <span class="k">this</span><span class="p">.</span><span class="nx">_firstName</span> <span class="o">=</span> <span class="s1">'Panda'</span><span class="p">;</span></span>
<span id="LC5" class="line" lang="javascript"></span>
<span id="LC6" class="line" lang="javascript"> <span class="c1">// good</span></span>
<span id="LC7" class="line" lang="javascript"> <span class="k">this</span><span class="p">.</span><span class="nx">firstName</span> <span class="o">=</span> <span class="s1">'Panda'</span><span class="p">;</span></span>
待完善
必须独占一行。
1 | // |
后跟一个空格,缩进与下一行被注释说明的代码一致。
避免使用
1 | /*...*/ |
这样的多行注释。有多行注释内容时,使用多个单行注释。
解释:注释块(/* ... /)中不能有(/或*/,JavaScript正则表达式中可能产生这种代码),这样会产生语法错误,有多行注释内容时,使用多个单行注释。
参考源码文件规范
JSDoc可以根据文档化注释,生成 JavaScript 应用程序或库、模块的API文档,现在很多编辑器或 IDE 中还可以通过 JSDoc 直接或使用插件生成智能提示。
详细规则请参考 Use JSDoc 和 JSDoc Guide;
对于内部实现、不容易理解的逻辑说明、摘要信息等,我们可能需要编写细节注释。
细节注释遵循单行注释的格式。说明必须换行时,每行是一个单行注释的起始。
1
2
3
4
5
6
7
<span id="LC1" class="line" lang="javascript"><span class="kd">function</span> <span class="nx">foo</span><span class="p">(</span><span class="nx">p1</span><span class="p">,</span> <span class="nx">p2</span><span class="p">,</span> <span class="nx">opt_p3</span><span class="p">)</span> <span class="p">{</span></span>
<span id="LC2" class="line" lang="javascript"> <span class="c1">// 这里对具体内部逻辑进行说明</span></span>
<span id="LC3" class="line" lang="javascript"> <span class="c1">// 说明太长需要换行</span></span>
<span id="LC4" class="line" lang="javascript"> <span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span></span>
<span id="LC5" class="line" lang="javascript"> <span class="p">....</span></span>
<span id="LC6" class="line" lang="javascript"> <span class="p">}</span></span>
<span id="LC7" class="line" lang="javascript"><span class="p">}</span></span>
特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
1 | FIXME |
或
1 | TODO |
的前缀可以帮助其他开发者快速了解这是一个需要复查的问题,或是给需要实现的功能提供一个解决方式。这将有别于常见的注释,因为它们是可操作的。
使用
1 | FIXME -- need to figure this out |
或者
1 | TODO -- need to implement |
1 | // TODO: 问题的解决方式,标记人,标记时间,[预计处理时间] |
标注待办事宜,表示需要实现,但目前还未实现的功能。
1
2
3
4
5
6
7
<span id="LC1" class="line" lang="javascript"><span class="kd">function</span> <span class="nx">Calculator</span><span class="p">()</span> <span class="p">{</span></span>
<span id="LC2" class="line" lang="javascript"></span>
<span id="LC3" class="line" lang="javascript"> <span class="c1">// TODO: 此字段应当配置到参数中 asoiso 2017-06-15</span></span>
<span id="LC4" class="line" lang="javascript"> <span class="k">this</span><span class="p">.</span><span class="nx">total</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span></span>
<span id="LC5" class="line" lang="javascript"></span>
<span id="LC6" class="line" lang="javascript"> <span class="k">return</span> <span class="k">this</span><span class="p">;</span></span>
<span id="LC7" class="line" lang="javascript"><span class="p">}</span></span>
1 | // FIXME: 问题描述,标记人,标记时间,[预计处理时间] |
标记某代码是错误的,而且不能工作,需要及时纠正的情况。
1
2
3
4
5
6
7
<span id="LC1" class="line" lang="javascript"><span class="kd">function</span> <span class="nx">Calculator</span><span class="p">()</span> <span class="p">{</span></span>
<span id="LC2" class="line" lang="javascript"></span>
<span id="LC3" class="line" lang="javascript"> <span class="c1">// FIXME: 此处不应该使用全局变量 asoiso 2017-06-15</span></span>
<span id="LC4" class="line" lang="javascript"> <span class="nx">total</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span></span>
<span id="LC5" class="line" lang="javascript"></span>
<span id="LC6" class="line" lang="javascript"> <span class="k">return</span> <span class="k">this</span><span class="p">;</span></span>
<span id="LC7" class="line" lang="javascript"><span class="p">}</span></span>
JavaScript 格式配置应用 WebStorm Code Style -> JavaScript -> Predefined Style -> JavaScript Standard Style 标准配置,拓展部分在下面补充。
遵循主流风格指南。
详细规则请参考 http://eslint.org/docs/rules/
详细规则请参考 https://palantir.github.io/tslint/rules/
上一篇:简单了解HTML5中的Web Notification桌面通知
支付宝扫一扫打赏
微信扫一扫打赏
共 0 条评论关于"【YQN】JavaScript \ EMCAScript \ TypeScript 编码规范"
最新评论