唯品秀前端博客
当前位置: 别具匠心 > 【YQN】JavaScript \ EMCAScript \ TypeScript 编码规范

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

2017-10-13 分类:别具匠心 作者:管理员 阅读(2484)

1 引言

1.1 说明

本文档以

1
Airbnb JavaScript Style Guide

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

1.2 基础

2 风格规范

2.1 命名

  • 使用
    1
    驼峰式(lowerCamelCase)

    命名变量和函数。


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
    帕斯卡式(UpperCamelCase)

    命名构造函数、类、枚举。


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
    全部字母大写,单词间下划线分隔(CONSTANT_CASE)

    的命名方式命名常量和枚举的属性


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 单行注释

必须独占一行。

1
//

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

2.2.2 多行注释

避免使用

1
/*...*/

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

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

2.2.3 文件注释

参考源码文件规范

2.2.4 文档化注释

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

详细规则请参考 Use JSDocJSDoc 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
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>

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 参考资料

「两年博客,如果觉得我的文章对您有用,请帮助本站成长」

赞(0) 打赏

谢谢你请我吃鸡腿*^_^*

支付宝
微信
0

谢谢你请我吃鸡腿*^_^*

支付宝
微信
标签:

上一篇:

下一篇:

共有 0 条评论 - 【YQN】JavaScript \ EMCAScript \ TypeScript 编码规范

博客简介

唯品秀博客: weipxiu.com,一个关注Web前端开发技术、关注用户体验、坚持更多原创实战教程的个人网站,愿景:成为宇宙中最具有代表性的前端博客,期待您的参与 

精彩评论

友情链接

他们同样是一群网虫,却不是每天泡在网上游走在淘宝和网游之间、刷着本来就快要透支的信用卡。他们或许没有踏出国门一步,但同学却不局限在一国一校,而是遍及全球!申请交换友链

站点统计

  • 文章总数: 219 篇
  • 草稿数目: 0 篇
  • 分类数目: 14 个
  • 独立页面: 6 个
  • 评论总数: 829 条
  • 链接总数: 13 个
  • 标签总数: 405 个
  • 建站时间: 943 天
  • 注册用户: 1257 人
  • 访问总量: 8872000 次
  • 最近更新: 2019年7月15日
服务热线:
 173xxxx7240

 QQ在线交流

 旺旺在线