【YQN】JavaScript \ EMCAScript \ TypeScript 编码规范

1 引言

1.1 说明

本文档以

为基础，编写符合自己团队的编码规范；
统一了命名和注释两大痛点，就统一了80%的风格，所以我们重点拓展这两部分内容，主体部分请参考基础。

1.2 基础

• JavaScript 中文版 | English
• ES5 中文版 | English
• React 中文版 | English
• CSS-in-JavaScript

2 风格规范

2.1驼峰命名(命名变量和函数)

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>

常用命名

待完善

2.2 注释

2.2.1 单行注释

必须独占一行。

后跟一个空格，缩进与下一行被注释说明的代码一致。

2.2.2 多行注释

避免使用

这样的多行注释。有多行注释内容时，使用多个单行注释。

解释：注释块（/* ... /）中不能有(/或*/，JavaScript正则表达式中可能产生这种代码)，这样会产生语法错误，有多行注释内容时，使用多个单行注释。

2.2.3 文件注释

参考源码文件规范

2.2.4 文档化注释

JSDoc可以根据文档化注释，生成 JavaScript 应用程序或库、模块的API文档，现在很多编辑器或 IDE 中还可以通过 JSDoc 直接或使用插件生成智能提示。

详细规则请参考 Use JSDoc 和 JSDoc Guide；

2.2.5 细节注释

对于内部实现、不容易理解的逻辑说明、摘要信息等，我们可能需要编写细节注释。
细节注释遵循单行注释的格式。说明必须换行时，每行是一个单行注释的起始。

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>

2.2.6 特殊注释

特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

给注释增加

或

的前缀可以帮助其他开发者快速了解这是一个需要复查的问题，或是给需要实现的功能提供一个解决方式。这将有别于常见的注释，因为它们是可操作的。
使用

或者

• 使用

  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>

2.3 格式

JavaScript 格式配置应用 WebStorm Code Style -> JavaScript -> Predefined Style -> JavaScript Standard Style 标准配置，拓展部分在下面补充。

• indent 使用4个空格缩进
• quotes 使用单引号
• semi 使用分号
• no-extra-semi 禁止多余的分号
• TypeScript 格式配置应用 WebStorm Code Style -> WebStorm Code Style -> Less 标准配置，拓展部分在下面补充。

3 语言规范

遵循主流风格指南。

4 代码检查

4.1 ESLint

详细规则请参考 http://eslint.org/docs/rules/

4.2 TSLint

详细规则请参考 https://palantir.github.io/tslint/rules/

5 参考资料

• https://github.com/airbnb/javascript
• https://google.github.io/styleguide/jsguide.html
• https://github.com/ecomfe/spec/blob/master/javascript-style-guide.md
• http://alloyteam.github.io/CodeGuide/
• https://github.com/aralejs/aralejs.github.io/issues/36
• http://usejsdoc.org/
• http://www.css88.com/doc/jsdoc/index.html
• https://github.com/aralejs/aralejs.github.io/issues/36
• https://github.com/aralejs/aralejs.github.io/wiki/JavaScript-注释规范