TypeScript编码规范

目的与声明

我们的目的是通过统一专业术语、统一规格标准的方式来提高团队整体协作的效率。

我们尊重每个成员的编码习惯，我们只纠正那些容易导致错误的不良习惯。

我们通过技术手段实现统一的编码规范，而非仅仅是口头约定。
我们的编码要求非常宽松，但是对于明显不符合要求的代码将拒绝签入。

编码格式

文件编码

统一使用 UTF-8 无 BOM 格式读写所有代码。

缩进

使用 1 个 TAB(占 4 个空格的宽度)(推荐)、4 个空格或 2 个空格创建缩进。

您在输入缩进时应使用 Tab 键，而不是使用空格键。
您在删除缩进时应使用 Shift+Tab 键，而不是使用退格键。

换行

您应该使用和操作系统相同的换行符。
这意味着您应该在 Windows 上使用 CR(Unicode 13) LF(Unicode 10) 作为换行符，
在 Mac/Linux 上使用 LF(Unicode 10) 作为换行符。

对于生成的代码应该忽略操作系统的区别，始终使用 LF 作为换行符。
在程序中您应该固定使用 '\n' 作为换行符。

空格

我们追加空格，可以让代码看起来不那么紧凑，减少阅读者的视觉压力。

代码中只允许使用空格键 (Unicode 32) 输入空格。

在单目运算符之间不追加空格：

-b
!!b

如果单目运算符是一个单词，则添加一个空格：

new Func
void 0
typeof x

在双目运算符左右追加一个空格：

x + y * 3
a = b + 1;
-x + ++y

在冒号、逗号、分号后追加一个空格(末尾除外)：

a = 1, b = 2
var a: number = 1;

在 if、for、while、switch、with 语句的括号前后追加空格：

if (a > 1) {

}
for (var i = 1; i < 2; i++) {

}
do {

} while(a < 1);

在函数声明的签名前后追加空格：

function fn(a, b) {

}

在匿名函数的签名前不追加空格

var fn = function(a, b) {

};

不建议为了对齐某些代码而手动添加空格，如下代码是不建议的：

var hello = 1;
var hi    = 2; // 不建议在此次故意追加空格以保持 = 对齐。
var not   = 3; // 不建议在此次故意追加空格以保持 = 对齐。

但是可以为了对齐注释而添加空格。

var hello = 1;   // 对齐的注释。
var hi = 2;      // 对齐的注释。
var not = 3;     // 对齐的注释。

在每行代码末尾可以出现任意个无用的空格。

在语法要求输入空格的地方只能输入一个空格。

新行

我们建议在每个代码段、每个成员声明之间追加一个空行。

import * as path from "path";

function fn1() {

}

function fn2() {

}

class A {

    fn1() {

    }

    fn2() {

    }

}

建议将 else、catch、finally 等子段写在一行：

if (a > 1) {

} else if (b > 1) {

} else {

}

try {

} catch(e) {

} finally {

}

我们允许将空且永久为空的 {} 写在一行如：

var obj = {};
function empty() {}

如果 {} 和 [] 内包含多个复杂的项，应分多行书写。

var a = {
    b: 1,
    c: 2,
    d: [],
    e: [1, 2, 3],
    f: [
        "aaa",
        "bbb",
        "ccc",
        "ddd",
        "eee"
    ]
};

我们建议在代码长度超过 120 时换行。
换行的位置应该是某个操作符末尾。

var a = "I'm a long long long " + // 将 + 放在末尾。
    "long long long text";

同一行代码换行后，新行增加一个缩进。

逗号

我们建议为{} 中的每个键值对末尾添加逗号。
如果这个对象未来可扩展，在最后一个键值对也应追加逗号。

var obj = {
    a: 1,
    b: 2, // 保留此逗号
};

enum A {
    a = 1,
    b = 2,
}

括号

不要为明确优先级的操作符添加括号。
如以下代码是不建议的：

a + (4 * b) // * 先算，不需要括号
typeof x // typeof 和 new 等类似是一个操作符，不需要括号

当判断一个赋值语句时，建议追加括号：

if ((x = 1)) { // 追加括号以表示这里不是将 == 误写成 =

}

立即执行的函数应使用括号：

(function() {

})();

不强制为每个 if、for、while 等语句添加 {}。

注释

所有 API 应使用 Java 风格的文档注释。

在文件顶部使用多行注释插入文件说明、版权声明等内容。

在代码中使用单行注释解释代码的目的。

其它

语句应固定以 } 或 ; 结尾。
一行内最多只能有一行语句。

不建议使用 with 语法。

对于无限循环，应使用 true 作为循环条件。

如果字符串内部是一段 HTML，则应该确保 HTML 使用双引号，外部字符串使用单引号。

允许使用 ?:、&& 和 || 代替 if 语句。

建议使用 `` 字符串书写多行字符串。

建议保持较低闭包嵌套级别。
当闭包嵌套级别超过 5 时，建议您重新整理代码。

不建议使用 [] 获取常量属性。

a["x"]   // 不建议
a.x      // 建议

命令规则

大小写

TypeScript 中命名规则统一为骆驼规则，即除了第一个单词，以后每个单词首字母大写，如 fileName:

function getName(userId) {
    var currentUserEnv = 1;
}

对于类型名应保持首字母大写:

class MyClass {

}
enum Weekday {

}

对于一个类的私有成员，可以追加 _ 前缀。

class User {

    private _name: string;

    getName() {
        return this._name;
    }

}

固定命名

用于保存 this 的变量名固定为 me。
用于保存 arguments 的变量名固定为 args。
用于循环的变量名固定为 i、j、k。
用于泛型的变量名固定为 T、K、R。

API 命名

原则上，公开 API 和参数不应该随意缩写英语单词。

除非这个缩写在 HTML、CSS、JavaScript 规范里已出现。

对于内部变量，则可以使用简写。

如果一个枚举的各项是可组合的标记位，则枚举类型为复数形式。
如果一个枚举的各项是独立的，则枚举类型名为单数形式。

属性名应主要为定主结构。
方法名应主要为动宾结构。

方法的动词部分采用第三人称形式。

文件命名

文件和文件夹按骆驼规则命名，首字母小写。

如果文件内有且只有一个成员，则文件名应和该成员相同。