فهرست منبع

typescript:feat:规范完善

haojianlong 4 سال پیش
والد
کامیت
c3f7e26eda

+ 1 - 0
docs/standard/index.js

@@ -12,6 +12,7 @@ const content = [
         path: '/standard/typescript',
         children:[
             {title: "注释", path: '/standard/typescript/comment.md'},
+            {title: "工具", path: '/standard/typescript/tools.md'},
             {title: "命名", path: '/standard/typescript/naming.md'},
             {title: "布局", path: '/standard/typescript/layout.md'},
         ]

+ 17 - 76
docs/standard/typescript/README.md

@@ -3,84 +3,25 @@
 [[toc]]
 :::
 
-::: tip 基本准则
+## 基本准则
 关于代码风格,没有谁对谁错,不同的人有不同的偏好。为了保持致的团队编码风格,降低代码阅读工作量,编码风格的确认采用最如下基本原则。
 
+* 代码风格要求可读性第一,效率第二。对于有特殊要求的代码,必须编写专门的详细的代码说明文档;
 * 编码偏好少数服从多数,个人服从团队;
-* 有争论时,由 teamleader 最终决定编码风格;
-* 使用 ```eslint ``` + ```prettier``` 规范代码风格。代码必须通 ```eslint``` 检查;
+* 有争论时,由 TeamLeader 最终决定编码风格;
+* 使用 ```eslint + prettier``` 规范代码风格。代码必须通 ```eslint``` 检查;
 * 为保持一致。当有更好的编码风格被团队受时,老代码也要修改为新的编码风格;
-:::
-
-## eslint
-### 安装
-```json{4-6}
-{
-    ......
-    "devDependencies": {
-        "@typescript-eslint/eslint-plugin": "^2.33.0",
-        "@typescript-eslint/parser": "^2.33.0",
-        "eslint": "^7.0.0",
-        "typescript": "^3.9.5"
-    },
-}
-```
-
-在项目文件夹下执行```npm install```命令安装 ```eslint``` 相关的包。
-
-### 配置
-在项目文件夹配置``` .eslintrc.js ```文件,推荐的配置如下。
-
-<PCodeGit repos="web/persagy-web" src="/persagy-web-base/.eslintrc.js" />
-
-## prettier
-```prettier``` 是一个流行的代码格式化工具。它能够解析代码,使用设定的规则来重新输出出格式规范的代码。它具有如下优点:
-* 可配置化
-* 支持多种语言
-* 集成多数的编辑器
-* 简洁的配置项
-* 与 ```eslint``` 搭配使用
-
-### 安装
-```prettier``` 可以使用全局安装或配置 ```package.json``` 的方式。
-
-**全局安装:**
-* 优点:在一台机器上安装一次,所有项目都可以使用。
-* 缺点:在其他未安装过的机器上下载项目,需要在新机器上手动安装。
-
-```shell
-C:\> npm install --global prettier
-```
-
-**使用 package.json:**
-* 优点:下载完项目后,执行 ```npm install``` 会自动完成所有的安装过程。不需要额外的操作。
-* 缺点:每个项目都需要安装;
-
-```json{4-6}
-{
-    ......
-    "devDependencies": {
-        "eslint-config-prettier": "^6.11.0",
-        "eslint-plugin-prettier": "^3.1.3",
-        "prettier": "^2.0.5",
-        "typescript": "^3.9.5"
-    },
-}
-```
-在项目文件夹下执行```npm install```命令安装 ```eslint``` 相关的包。
-
-空函数会降低可读性,因为读者需要猜测它是否是有意的。因此,为空函数写一个明确的评论是一个好习惯。
-
-
-----------------------------
-```typescript
-function foo() {
-    // do nothing.
-}
-```
 
-尤其是,箭头函数的空白块可能会让开发人员感到困惑。这与空对象文字非常相似。
-```typescript
-list.map(() => {});   // This is a block, would return undefined.
-list.map(() => ({})); // This is an empty object.
-```
+## 编码规范
+* 每个源码文件都必须加注释头。
+* 所有的类、接口、枚举、函数、属性、入参、返回值都必须加注释。
+* 一行代码不超过 120 个字符,单个函数的程序行数不超过 200 行。
+* 不使用的代码,尽早删除,避免垃圾程序。
+* 属性的作用域尽可能小,在没有明确要求前,优先使用 ```private``` 。优先级 ```private->protected->public```。
+* 变量优先使用 ```const``` 定义,除非在后续的代码中要修改变量的值改为 let 。
+* 对表达式容易混淆优先级的运算符,使用括号以避免二义性。
+* 利用缩进来显示程序的逻辑结构,缩进量一致并以 Tab 键为单位(定义 Tab 为 4 个空格)。
+* 循环、分支嵌套层次不要超过五层。
+* 注释可以与语句在同一行的右端,也可以在上行。
+* 一目了然的语句不加注释。
+* 代码的注释率(注释行数/文件总行数)不低于 30%。

+ 58 - 17
docs/standard/typescript/comment.md

@@ -3,12 +3,56 @@
 [[toc]]
 :::
 
+注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码。
+
 多行注释规则:
 * 注释以“/**”开始,以“*/”结尾。
 * "/**"与“*/”各占一行;
 * 每一行注释都以“*”打头,在“*”与注释内容之间间隔一个空格;
 
-## 文件头
+## 写注释注意事项
+### 什么时候编写注释
+修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要及时删除。
+
+### 内容要求
+注释格式尽量统一,使用“/** …… */”形式的注释。
+
+注释语言不统一,影响程序易读性和外观排版。建议多使用中文,不是参与项目的所有人员都能流利的使用英语,出于对维护人员的考虑,建议使用中文。
+
+注释的内容要清楚、明了,含义准确,防止注释二义性。错误的注释不但无益反而有害。
+
+尽量不要使用长句子描述,长句的句法结构过于复杂,不利于维护人员理解。要将长句子分解成多个短句来描述。
+
+避免在注释中使用缩写,特别是非常用缩写。在使用缩写时或之前,应对缩写进行必要的说明。
+
+### 注释的合理位置
+注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面。
+
+除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。
+
+类型的声明(包括类、接口、枚举等),必须加以注释。对类型的注释应放在其上方相邻位置,不可放在下面;对枚举的每个枚举值的注释放在此枚举的右方。
+
+注释与所描述内容进行同样的缩排,让程序排版整齐,并方便注释的阅读与理解。
+
+### 注释颗料度要求
+所有的类、接口、枚举必须编写注释。
+
+类的函数、属性、变量必须写注释。
+
+函数的所有入参、返回值都必须写注释。
+
+所有的分支语句(if、else、switch 等)、循环语句(for、while、do...while 等)必须编写注释。
+
+switch 的每个 case 分枝都必须写注释。注释写在 ```case``` 语句右端。
+
+对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。
+
+在顺序执行的程序中,每隔3—5行语句,应当加一个注释,注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。
+
+注释与其上面的代码用空行隔开。
+
+## 注释分类
+### 文件头
 文件头注释是标识、是旗帜、是团魂。代表了开发团队对所写代码的负责精神。文件头统一使用如下注释:
 
 ```typescript
@@ -39,7 +83,7 @@
  */
 ```
 
-## 类与接口注释
+### 类与接口注释
 **格式:**
 ```typescript
 /**
@@ -86,10 +130,10 @@ export class SObject {}
  *
  *  @author  庞利祥 <sybotan@126.com>
  * */
-export interface SCommandLog {}
+export interface SICommandLog {}
 ```
 
-## 函数
+### 函数
 **格式:**
 ```typescript
 /**
@@ -124,9 +168,9 @@ export interface SCommandLog {}
 * 多个参数数描述使用 tab 键完成对齐排版;
 * 一个入参有多种类型时,每种类型的描述使用 “|” 分开。注意描述与“|”留至少一个空格。
 * 入参与返回值描述与简要描述之间隔一空行;
-* 函数最多只能有一个 @return 标识。如果函数类的返回类型为 void ,则没有 @return 标识;
+* 函数最多只能有一个 @return 标识。如果函数类的返回类型为 ```void``` ,则没有 @return 标识;
 * @return 标识不能排在 @param 标识前边;
-* @return 标识与返回值描述间用 tab 键完成定位;
+* @return 标识与返回值描述间用 ```tab``` 键完成定位;
 
 **示例:**
 
@@ -199,7 +243,7 @@ export class SRect {
 }
 ```
 
-## 属性
+### 属性
 **格式:**
 ```typescript
 /** summary */
@@ -213,8 +257,8 @@ export class SRect {
 * “/**”、简要说明与“*/”在同一行;
 * "/**"、简要说明与“*/”之间隔一个空格;
 * 域属性的注释写在域;
-* 没有域的属性,写在 get 操作上;
-* 没有 get 操作,写在 set 操作上;
+* 没有域的属性,写在 ```get``` 操作上;
+* 没有 ```get``` 操作,写在 ```set``` 操作上;
 
 **示例:**
 ```typescript{2,5,13}
@@ -241,7 +285,7 @@ export class SRect {
 }
 ```
 
-## 枚举
+### 枚举
 **格式:**
 * 枚举类注释
 ```typescript
@@ -283,16 +327,13 @@ export class SRect {
  * @author  庞利祥 <sybotan@126.com>
  */
 export enum STouchState {
-    /** 标准状态 */
-    None,
-    /** 移动状态 */
-    Move,
-    /** 缩放状态 */
-    Zoom,
+    None,       /** 标准状态 */
+    Move,       /** 移动状态 */
+    Zoom,       /** 缩放状态 */
 }
 ```
 
-## 内部注释
+### 内部注释
 待定
 ```typescript
 

+ 58 - 0
docs/standard/typescript/layout.md

@@ -2,3 +2,61 @@
 ::: details 目录
 [[toc]]
 :::
+
+## 基本要求
+* 一个文件中只能定义一个类。
+* 每行字符不超过 120 个字符,一个函数最多 200 行代码。
+* 一行只允许有一条语句。
+* 一行只允许定义一个变量。
+* ```if```、```else if```、```else```、```for```、```while``` 强制使用大括号。只有一行代码也要用大括号括起来。
+* 不得省略语句结束的分号。
+* 类的 ```public``` 类型属性与函数不加访问修饰符;
+* 如果函数没有返回值,必需使用 ```void```;
+* 如果函数体为空,必须加注释”```// do nothing```“明确标明。
+```typescript
+f(x: number, y: string): void {
+    // do nothing
+}
+```
+* 如果函数还未完成,必须加注释”```// todo: ```原因“标明。
+```typescript
+typeList(): Array<string> {
+    // todo: 类型列表未确认
+    return null;
+}
+```
+
+## 程序各部分的放置顺序
+* 文件注释头
+* ```import``` 导入引用的包
+* 类、接口、枚举注释
+* 定义类、接口、枚举
+* 属性按 ```public```、```protected```、```private``` 顺序定义。相关的属性定义在一起
+* 构造函数的定义放在所有函数前
+* 函数按 ```public```、```protected```、```private``` 顺序定义。相关的函数定义在一起
+* 重载函数时,实现函数放在重载函数的最后
+
+## 留空
+### 空行
+* 相对独立的程序块之间应加空行。
+* 代码块之间需隔一个空行(即”}“符号后跟一个空行),如果”}“后是上层代码的”}“,则不加空行。
+* 属性定义与函数定义之间隔一空行。
+* 属性与属性之间隔一空行。
+* 属性的 ```get```/```set``` 不留空行。
+* 每个函数定义与之前的代码之间隔一空行。
+
+### 缩进
+* 禁止使用空格和 tab 混合缩进,缩进控制每级 4 个空格。
+* 代码层级通过”{“与"}”标注,“{”进一级,“}”退一级。
+* “{”与代码定义(类、接口、枚举、函数、```if```、```switch```、```for```、```while等```)处于同一行。
+* ```switch``` 与 ```case``` 为同级代码(缩进相同),```case``` 后代码缩进一级。
+
+### 空格
+* 逗号,冒号后要有一个空格。
+* 运算符(数值、关系、逻辑)前后要有一个空格。非运算符(!)与取负运算符(-)不要空格。
+* 类的继承符号“:“前后要保留一个空格。
+* 函数返回类型,“:”与括号之间无空格,与返回值类型间有一个空格。
+* 函数名与小括号间没有空格。
+* 定义变量、属性、函数入参。名称后直接跟”:“,不需要空格。”:“与类型之间有一个空格。
+* 小括号里开始不需要空格。
+* ```for```、```if```、```else```、```switch``` 与小括号间有一个空格。

+ 4 - 13
docs/standard/typescript/naming.md

@@ -4,11 +4,11 @@
 :::
 
 ## 标识符
-标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解——尽量采用采用英文单词或全部中文全拼表示。
+标识符的命名要清晰、明了,有明确含义。使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。尽量采用采用英文单词或全部中文全拼表示。
 
 * 标识符只能使用字母,数字与“_”。
 * 首字符不能是数字;
-* 只有私有字段前缀使用“_”;
+* 只有私有变量前缀使用“_”;
 * 全局常量的各单词间使用“_”分隔;
 
 ## 大小写
@@ -36,18 +36,9 @@
 | 事件回调     | Camel   | onMouseUp(event: SMouseEvent): boolean |
 | 枚举类型     | Pascal   | export enum STouchState {None, Move} |
 | 枚举值       | Pascal   | export enum STouchState {None, Move} |
-| 字段        | Camel    | size: SSize; |
-| 私有字段     | Camel    | private _bg: SColor; |
+| 变量        | Camel    | size: SSize; |
+| 私有变量     | Camel    | private _bg: SColor; |
 | 参数        | Camel    | translate(dx: number, dy: number): void |
 | 局部变量     | Camel    | let x0 = 10; |
 | 泛型        | 大写字母   | identity\<T>(arg: T): T {return arg;} |
 | 全局常量     | 大写Snake | const BG_COLOR = SColor.Blue; |
-
-## 前缀
-::: tip 提示
-前缀规范只适用于库代码。
-::
-
-* 所有的类、枚举都加“P”前缀;
-* 所有的接口类都加“PI”前缀;
-* 所有的私有字段都加“_”前缀;

+ 89 - 0
docs/standard/typescript/tools.md

@@ -0,0 +1,89 @@
+# 代码规范工具
+::: details 目录
+[[toc]]
+:::
+
+## eslint
+
+### 安装
+配置 ```package.json``` 增加 ```eslint``` 依赖。
+```json{4-6}
+{
+    ......
+    "devDependencies": {
+        "@typescript-eslint/eslint-plugin": "^2.33.0",
+        "@typescript-eslint/parser": "^2.33.0",
+        "eslint": "^7.0.0",
+        "typescript": "^3.9.5"
+    },
+}
+```
+
+在项目文件夹下执行```npm install```命令安装 ```eslint``` 相关的包。
+
+### 配置
+在项目文件夹配置 ```.eslintrc.js``` 文件,推荐的配置如下。
+
+<PCodeGit repos="web/persagy-web" src="/persagy-web-base/.eslintrc.js" lang="javascript" />
+
+有时 IDE 开发环境的编辑器与 ```eslint``` 的编码风格不一致。因此需要修改相关的配置文件。在项目文件夹配置 ```.editorconfig``` 文件。推荐的配置如下。
+
+<PCodeGit repos="web/persagy-web" src="/persagy-web-base/.editorconfig" lang="javascript" />
+
+### 使用
+配置 ```package.json``` 增加 ```lint``` 脚本命令。
+
+```json{6}
+{
+    ......
+    "scripts": {
+        "build": "tsc",
+        "publish": "npm publish",
+        "lint": "eslint src/**/*.{js,ts,tsx}",
+        "test": "jest",
+        "typedoc": "typedoc --hideGenerator src",
+        "publish-doc": "node publish.js"
+    },
+    ......
+}
+```
+
+在项目文件夹下执行```npm run lint```命令进行代码风格简查。没出任何报错信息,则通过代码审查。
+
+```shell
+D:\Sybotan\graph>npm run lint
+
+> sybotan-graph@2.2.72 lint D:\Sybotan\graph
+> eslint src/**/*.{js,ts,tsx}
+
+
+D:\Sybotan\graph>
+```
+
+## prettier
+```prettier``` 是一个流行的代码格式化工具。它能够解析代码,使用设定的规则来重新输出出格式规范的代码。它具有如下优点:
+* 可配置化
+* 支持多种语言
+* 集成多数的编辑器
+* 简洁的配置项
+* 与 ```eslint``` 搭配使用
+
+### 安装
+配置 ```package.json``` 增加 ```prettier``` 依赖。
+
+```json{4-6}
+{
+    ......
+    "devDependencies": {
+        "eslint-config-prettier": "^6.11.0",
+        "eslint-plugin-prettier": "^3.1.3",
+        "prettier": "^2.0.5",
+        "typescript": "^3.9.5"
+    },
+}
+```
+
+在项目文件夹下执行```npm install```命令安装 ```prettier``` 相关的包。
+
+### 使用
+没想好怎么写 ):?