Add new topic: Coding Guidelines

Author: zhongsp

README.md

@@ -35,6 +35,7 @@ TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
 * [与其它构建工具整合](./doc/handbook/Integrating with Build Tools.md)
 * [NPM包的类型](./doc/handbook/Typings for NPM Packages.md)
 * Wiki
+  * [编码规范](./doc/handbook/coding_guidelines.md)
   * [常见编译错误](./doc/handbook/Common Errors.md)
   * [支持TypeScript的编辑器](./doc/handbook/TypeScript-Editor-Support.md)
   * [结合ASP.NET v5使用TypeScript](./doc/handbook/Using-TypeScript-With-ASP.NET-5.md)
@@ -50,10 +51,6 @@ TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
 * Read [TypeScript Language Specification (Recommended)](https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md)
 * Read [TypeScript 语言规范 (译完第一章)](./doc/TypeScript Language Specification.md)
 
-**Others**
-
-* [编码规范](./doc/coding_guidelines.md)
-
 I'd love for you to contribute to the translation:)
 
 

SUMMARY.md

@@ -26,6 +26,7 @@
 * [与其它构建工具整合](./doc/handbook/Integrating with Build Tools.md)
 * [NPM包的类型](./doc/handbook/Typings for NPM Packages.md)
 * Wiki
+  * [编码规范](./doc/handbook/coding_guidelines.md)
   * [常见编译错误](./doc/handbook/Common Errors.md)
   * [支持TypeScript的编辑器](./doc/handbook/TypeScript-Editor-Support.md)
   * [结合ASP.NET v5使用TypeScript](./doc/handbook/Using-TypeScript-With-ASP.NET-5.md)

doc/coding_guidelines.md renamed to doc/handbook/coding_guidelines.md

@@ -1,54 +1,70 @@
-这个编码规范是给开发TypeScript团队开发TypeScript时使用的。对于我们使用TypeScript的用户来说不一定适用，仅做参考吧。
+<!-- markdownlint-disable MD005 -->
+<!-- markdownlint-disable MD029 -->
+
+这个编码规范是给TypeScript开发团队在开发TypeScript时使用的。
+对于使用TypeScript的普通用户来说不一定适用，但是可以做为一个参考。
 
 ## 命名
+
 1. 使用PascalCase为类型命名。
-1. 不要使用`I`做为接口名前缀。
-1. 使用PascalCase为枚举值命名。
-1. 使用camelCase为函数命名。
-1. 使用camelCase为属性或本地变量命名。
-1. 不要为私有属性名添加`_`前缀。
-1. 尽可能使用完整的单词拼写命名。
-
-## 组件 
+2. 不要使用`I`做为接口名前缀。
+3. 使用PascalCase为枚举值命名。
+4. 使用camelCase为函数命名。
+5. 使用camelCase为属性或本地变量命名。
+6. 不要为私有属性名添加`_`前缀。
+7. 尽可能使用完整的单词拼写命名。
+
+## 组件
+
 1. 1个文件对应一个逻辑组件 （比如：解析器，检查器）。
-1. 不要添加新的文件。 :)
-1. `.generated.*`后缀的文件是自动生成的，不要手动改它。
+2. 不要添加新的文件。 :)
+3. `.generated.*`后缀的文件是自动生成的，不要手动改它。
 
 ## 类型
+
 1. 不要导出类型/函数，除非你要在不同的组件中共享它。
-1. 不要在全局命名空间内定义类型/值。
-1. 共享的类型应该在`types.ts`里定义。
-1. 在一个文件里，类型定义应该出现在顶部。
+2. 不要在全局命名空间内定义类型/值。
+3. 共享的类型应该在`types.ts`里定义。
+4. 在一个文件里，类型定义应该出现在顶部。
+
+## `null` 和 `undefined`：
 
-## `null` 和 `undefined`:
 1. 使用 **undefined**，不要使用 null。
 
 ## 一般假设
+
 1. 假设像Nodes，Symbols等这样的对象在定义它的组件外部是不可改变的。不要去改变它们。
-1. 假设数组是不能改变的。
+2. 假设数组是不能改变的。
 
 ## 类
+
 1. 为了保持一致，在核心编译链中不要使用类，使用函数闭包代替。
-  
+
 ## 标记
+
 1. 一个类型中有超过2个布尔属性时，把它变成一个标记。
 
 ## 注释
+
 为函数，接口，枚举类型和类使用JSDoc风格的注释。
 
 ## 字符串
+
 1. 使用双引号`""`
-1. 所有要展示给用户看的信息字符串都要做好本地化工作（在diagnosticMessages.json中创建新的实体）。
+2. 所有要展示给用户看的信息字符串都要做好本地化工作（在diagnosticMessages.json中创建新的实体）。
 
 ## 错误提示信息
+
 1. 在句子结尾使用`.`。
-1. 对不确定的实体使用不定冠词。
-1. 确切的实体应该使用名字（变量名，类型名等）
-1. 当创建一条新的规则时，主题应该使用单数形式（比如：An external module cannot...而不是External modules cannot）。
-1. 使用现在时态。
+2. 对不确定的实体使用不定冠词。
+3. 确切的实体应该使用名字（变量名，类型名等）
+4. 当创建一条新的规则时，主题应该使用单数形式（比如：An external module cannot...而不是External modules cannot）。
+5. 使用现在时态。
 
 ## 错误提示信息代码
+
 提示信息被划分类成了一般的区间。如果要新加一个提示信息，在上条代码上加1做为新的代码。
+
 * 1000 语法信息
 * 2000 语言信息
 * 4000 声明生成信息
@@ -59,22 +75,27 @@
 ## 普通方法
 
 由于种种原因，我们避免使用一些方法，而使用我们自己定义的。
+
 1. 不使用ECMAScript 5函数；而是使用[core.ts](https://github.com/Microsoft/TypeScript/blob/master/src/compiler/core.ts)这里的。
-1. 不要使用`for..in`语句；而是使用`ts.forEach`，`ts.forEachKey`和`ts.forEachValue`。注意它们之间的区别。
-1. 如果可能的话，尝试使用`ts.forEach`，`ts.map`和`ts.filter`代替循环。
+2. 不要使用`for..in`语句；而是使用`ts.forEach`，`ts.forEachKey`和`ts.forEachValue`。注意它们之间的区别。
+3. 如果可能的话，尝试使用`ts.forEach`，`ts.map`和`ts.filter`代替循环。
 
 ## 风格
 
 1. 使用arrow函数代替匿名函数表达式。
-1. 只要需要的时候才把arrow函数的参数括起来。<br />比如，`(x) => x + x`是错误的，下面是正确的做法：
+2. 只要需要的时候才把arrow函数的参数括起来。<br />比如，`(x) => x + x`是错误的，下面是正确的做法：
+
   1. `x => x + x`
   2. `(x,y) => x + y`
   3. `<T>(x: T, y: T) => x === y`
-1. 总是使用`{}`把循环体和条件语句括起来。
+
+3. 总是使用`{}`把循环体和条件语句括起来。
 4. 开始的`{`总是在同一行。
 5. 小括号里开始不要有空白. <br />逗号，冒号，分号后要有一个空格。比如：
+
   1. `for (var i = 0, n = str.length; i < 10; i++) { }`
   2. `if (x < 10) { }`
   3. `function f(x: number, y: string): void { }`
+
 6. 每个变量声明语句只声明一个变量 <br />（比如 使用 `var x = 1; var y = 2;` 而不是 `var x = 1, y = 2;`）。
 7. `else`要在结束的`}`后另起一行。

preface.md

@@ -47,6 +47,7 @@ TypeScript目前还在积极的开发完善之中，不断地会有新的特性
 * [与其它构建工具整合](./doc/handbook/Integrating with Build Tools.html)
 * [NPM包的类型](./doc/handbook/Typings for NPM Packages.html)
 * Wiki
+  * [编码规范](./doc/handbook/coding_guidelines.html)
   * [常见编译错误](./doc/handbook/Common Errors.html)
   * [支持TypeScript的编辑器](./doc/handbook/TypeScript-Editor-Support.html)
   * [结合ASP.NET v5使用TypeScript](./doc/handbook/Using-TypeScript-With-ASP.NET-5.html)
@@ -55,6 +56,7 @@ TypeScript目前还在积极的开发完善之中，不断地会有新的特性
 
 ## 主要修改
 
+* 2016-01-23 新增章节：[编码规范](./doc/handbook/coding_guidelines.html)
 * 2016-01-23 新增章节：[架构概述](./doc/handbook/Architectural-Overview.html)
 * 2015-12-27 新增章节：[结合ASP.NET v5使用TypeScript](./doc/handbook/Using-TypeScript-With-ASP.NET-5.html)
 * 2015-12-26 新增章节：[支持TypeScript的编辑器](./doc/handbook/TypeScript-Editor-Support.html)