Browse Source

typescript:feat:typescript规范调整

haojianlong 4 years ago
parent
commit
a4b7fd1c5b

+ 1 - 1
docs/.vuepress/config.js

@@ -93,7 +93,7 @@ module.exports = {
                 text:"开发规范",
                 items: [
                     {text: "javascript", link: "/standard/javascript.md"},
-                    {text: "typescript", link: "/standard/typescript.md"},
+                    {text: "typescript", link: "/standard/typescript/"},
                     {text: "约定", link: "/standard/appoint.md"},
                     {text: "git", link: "/standard/git.md"},
                     {text: "typescript 自动生成 api 文档", link: "/standard/typedoc.md"},

+ 1 - 1
docs/guides/README.md

@@ -4,4 +4,4 @@
 
 测试
 
-<GitCode project="/web/persagy-web" fileUrl="/persagy-web-big/src/index.ts"/>
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/index.ts"/>

+ 1 - 1
docs/guides/big/items/column.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/SColumnItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/SColumnItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/big/items/door.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/SDoorItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/SDoorItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/big/items/space.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/SSpaceItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/SSpaceItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/big/items/virtualWall.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/SVirtualWallItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/SVirtualWallItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/big/items/wall.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/SWallItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/SWallItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/big/items/window.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/SWindowItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/SWindowItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/big/items/zone.md

@@ -5,7 +5,7 @@
 
 ## 源代码
 
-<GitCode fileUrl="/persagy-web-big/src/items/floor/ZoneItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-big/src/items/floor/ZoneItem.ts" />
 
 ## 代码说明
     

+ 1 - 1
docs/guides/scene/items/area.md

@@ -4,7 +4,7 @@
 [[toc]]
 :::
 
-<GitCode fileUrl="/persagy-web-graph/src/items/SGraphAreaGroupItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-graph/src/items/SGraphAreaGroupItem.ts" />
 
 <scene-items-area />
 

+ 1 - 1
docs/guides/scene/items/polygon.md

@@ -6,7 +6,7 @@
 
 ## item 实例
 
-<GitCode fileUrl="/persagy-web-graph/src/items/SGraphPolyGroupItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-graph/src/items/SGraphPolyGroupItem.ts" />
 
 <scene-items-polygon />
 

+ 1 - 1
docs/guides/scene/items/rect.md

@@ -7,7 +7,7 @@
 
 ## item 实例
 
-<GitCode fileUrl="/persagy-web-graph/src/items/SGraphRectItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-graph/src/items/SGraphRectItem.ts" />
 
 <scene-items-rect />
 

+ 1 - 1
docs/guides/scene/items/svg.md

@@ -5,7 +5,7 @@
 :::
 ## item 实例
 
-<GitCode fileUrl="/persagy-web-graph/src/items/SGraphSvgItem.ts" />
+<PCodeGit repos="web/persagy-web" src="/persagy-web-graph/src/items/SGraphSvgItem.ts" />
 
 <scene-items-svg />
 

+ 6 - 1
docs/standard/index.js

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

+ 0 - 4
docs/standard/typedoc.md

@@ -1,7 +1,3 @@
----
-sidebarDepth: 2
----
-
 # TypeScript 文档注释规范
 ::: details 目录
 [[toc]]

+ 0 - 76
docs/standard/typescript.md

@@ -1,76 +0,0 @@
-# typescript 编写规范
-
-::: details 目录
-[[toc]]
-:::
-
-
-## 命名
-
-1. 使用<font color=red> PascalCase </font>为类型命名。
-2. 不要使用I做为接口名前缀。
-3. 使用<font color=red> PascalCase </font>为枚举值命名。
-4. 使用<font color=red> camelCase </font>为函数命名。
-5. 使用<font color=red> camelCase </font>为属性或本地变量命名。
-6. 不要为私有属性名添加_前缀。
-7. 尽可能使用完整的单词拼写命名。
-
-## 组件
-
-1. 1个文件对应一个逻辑组件 (比如:解析器,检查器)。
-2. <font color=red> .generated.*  </font>后缀的文件是自动生成的,不要手动改它。
-3. 不要导出类型/函数,除非你要在不同的组件中共享它。
-4. 不要在全局命名空间内定义类型/值。
-5. 共享的类型应该在<font color=red> types.ts </font>里定义。
-6. 在一个文件里,类型定义应该出现在顶部。
-
-## null和undefined
-
-使用``` undefined ```,不要使用``` null```。
-
-## 标记
-
-一个类型中有超过2个布尔属性时,把它变成一个标记。
-
-## 注释
-
-为函数,接口,枚举类型和类使用[JSDoc](javascript.md)风格的注释。
-
-## 字符串
-
-1. 使用双引号""
-2. 所有要展示给用户看的信息字符串都要做好本地化工作(在<font color=red> diagnosticMessages.json </font>中创建新的实体)。
-
-## 错误提示信息
-
-1. 在句子结尾使用。
-2. 对不确定的实体使用不定冠词。
-3. 确切的实体应该使用名字(变量名,类型名等)
-4. 当创建一条新的规则时,主题应该使用单数形式(比如:An external module cannot...而不是External modules cannot)。
-5. 使用现在时态。
-6. 错误提示信息代码
-7. 提示信息被划分类成了一般的区间。如果要新加一个提示信息,在上条代码上加1做为新的代码。
-
-| 提示 | 意义 |
-| :-: | :-: |
-| 1000 | 语法信息 |
-| 2000 | 语言信息 |
-| 4000 | 声明生成信息 |
-| 5000 | 编译器选项信息 |
-| 6000 | 命令行编译器信息 |
-| 7000 | noImplicitAny信息 |
-
-## 风格
-
-1. 使用<font color=red> arrow </font>函数代替匿名函数表达式。
-2. 只要需要的时候才把arrow函数的参数括起来。
-3. 总是使用{}把循环体和条件语句括起来。
-4. 开始的{总是在同一行。
-5. 小括号里开始不要有空白。
-6. 逗号,冒号,分号后要有一个空格。
-7. 每个变量声明语句只声明一个变量
-   (比如 使用var x = 1; var y = 2;而不是var x = 1, y = 2;)。
-8. <font color=red> else </font>要在结束的}后另起一行。
-
-
-

+ 86 - 0
docs/standard/typescript/README.md

@@ -0,0 +1,86 @@
+# TypeScript 编码风格
+::: details 目录
+[[toc]]
+:::
+
+::: tip 基本准则
+关于代码风格,没有谁对谁错,不同的人有不同的偏好。为了保持致的团队编码风格,降低代码阅读工作量,编码风格的确认采用最如下基本原则。
+
+* 编码偏好少数服从多数,个人服从团队;
+* 有争论时,由 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.
+```

+ 299 - 0
docs/standard/typescript/comment.md

@@ -0,0 +1,299 @@
+# 注释
+::: details 目录
+[[toc]]
+:::
+
+多行注释规则:
+* 注释以“/**”开始,以“*/”结尾。
+* "/**"与“*/”各占一行;
+* 每一行注释都以“*”打头,在“*”与注释内容之间间隔一个空格;
+
+## 文件头
+文件头注释是标识、是旗帜、是团魂。代表了开发团队对所写代码的负责精神。文件头统一使用如下注释:
+
+```typescript
+/*
+ * *********************************************************************************************************************
+ *
+ *          !!
+ *        .F88X
+ *        X8888Y
+ *      .}888888N;
+ *        i888888N;        .:!              .I$WI:
+ *          R888888I      .'N88~            i8}+8Y&8"l8i$8>8W~'>W8}8]KW+8IIN"8&
+ *          .R888888I    .;N8888~          .X8'  "8I.!,/8"  !%NY8`"8I8~~8>,88I
+ *            +888888N;  .8888888Y                                  "&&8Y.}8,
+ *            ./888888N;  .R888888Y        .'}~    .>}'.`+>  i}!    "i'  +/'  .'i~  !11,.:">,  .~]!  .i}i
+ *              ~888888%:  .I888888l      .]88~`1/iY88Ii+1'.R$8$8]"888888888>  Y8$  W8E  X8E  W8888'188Il}Y88$*
+ *              18888888    E8888881    .]W%8$`R8X'&8%++N8i,8N%N8+l8%`  .}8N:.R$RE%N88N%N$K$R  188,FE$8%~Y88I
+ *            .E888888I  .i8888888'      .:$8I;88+`E8R:/8N,.>881.`$8E/1/]N8X.Y8N`"KF&&FK!'88*."88K./$88%RN888+~
+ *            8888888I  .,N888888~        ~88i"8W,!N8*.I88.}888%F,i$88"F88"  888:E8X.>88!i88>`888*.}Fl1]*}1YKi'
+ *          i888888N'      I888Y          ]88;/EX*IFKFK88X  K8R  .l8W  88Y  ~88}'88E&%8W.X8N``]88!.$8K  .:W8I
+ *        .i888888N;        I8Y          .&8$  .X88!  i881.:%888>I88  ;88]  +88+.';;;;:.Y88X  18N.,88l  .+88/
+ *      .:R888888I
+ *      .&888888I                                          Copyright (c) 2016-2020.  博锐尚格科技股份有限公司
+ *        ~8888'
+ *        .!88~                                                                     All rights reserved.
+ *
+ * *********************************************************************************************************************
+ */
+```
+
+## 类与接口注释
+**格式:**
+```typescript
+/**
+ * summary
+ *
+ * @author  author-text
+ */
+```
+
+**说明:**
+* *summary*
+
+&emsp;&emsp;    简要说明。
+
+* *author-text*
+
+&emsp;&emsp;    作者描述。描述要包含作者的姓名与邮箱地址。
+
+**风格:**
+* 作者与简要说明隔一空行;
+* @author 标识与作者间用 tab 键完成定位;
+* 多个作者,使用多个 @author 标记,每个作者占一行;
+* 姓名与㞨箱地址间隔一个空格;
+* 邮箱地址使用”<>“括起来。
+* 多个作者间不能有空行;
+
+**示例:**
+
+* 类注释
+```typescript
+/**
+ * 对象
+ *
+ * @author  庞利祥 <sybotan@126.com>
+ * @author  庞凌峰 <sandy@126.com>
+ */
+export class SObject {}
+```
+
+* 接口注释
+```typescript
+/**
+ *  命令日志接口
+ *
+ *  @author  庞利祥 <sybotan@126.com>
+ * */
+export interface SCommandLog {}
+```
+
+## 函数
+**格式:**
+```typescript
+/**
+  * summary
+  *
+  * @param   parameter-name     description
+  * @return  return-description
+  */
+```
+**说明:**
+* *summary*
+
+&emsp;&emsp;    简要说明。
+
+* *parameter-name*
+
+&emsp;&emsp;    参数名
+
+* *description*
+
+&emsp;&emsp;    参数描述
+
+* *return-description*
+
+&emsp;&emsp;    返回值描述
+
+**风格:**
+* 入参与出参与简要说明隔一空行;
+* 入参的顺序要与函数的定义保持一致;
+* 入参以有多个,每个入参单独占一行;
+* @param 标识与参数名间用 tab 键完成定位;
+* 多个参数数描述使用 tab 键完成对齐排版;
+* 一个入参有多种类型时,每种类型的描述使用 “|” 分开。注意描述与“|”留至少一个空格。
+* 入参与返回值描述与简要描述之间隔一空行;
+* 函数最多只能有一个 @return 标识。如果函数类的返回类型为 void ,则没有 @return 标识;
+* @return 标识不能排在 @param 标识前边;
+* @return 标识与返回值描述间用 tab 键完成定位;
+
+**示例:**
+
+* 有入参与返回值
+```typescript{5-7}
+export class SRect {
+    /**
+     * 生成平移矩形
+     *
+     * @param   dx      x 轴位移
+     * @param   dy      y 轴位移
+     * @return  移动后的矩形
+     */
+    translated(dx: number, dy: number): SRect {
+        return new SRect(this.x + dx, this.y + dy, this.width, this.height);
+    }
+}
+```
+
+* 多类型入参
+```typescript{5-8}
+export class SRect {
+    /**
+     * 构造函数
+     *
+     * @param   x           x 轴坐标 | 左上角坐标
+     * @param   y           y 轴坐标 | 右下角坐标 | 大小
+     * @param   width       宽度
+     * @param   height      高度
+     */
+    constructor(
+        x?: number | SPoint,
+        y?: number | SPoint | SSize,
+        width?: number,
+        height?: number
+    ) {}
+}
+```
+
+* 无返回值
+```typescript{5,6}
+export class SRect {
+   /**
+     * 平移矩形
+     *
+     * @param   dx      x 轴位移
+     * @param   dy      y 轴位移
+     */
+    translate(dx: number, dy: number): void {
+        this.x += dx;
+        this.y += dy;
+    }
+}
+```
+
+* 只有返回值
+```typescript{5}
+export class SRect {
+    /**
+     * 计算中心点
+     *
+     * @return  中心点坐标
+     */
+    center(): SPoint {
+        return new SPoint(
+            this.x + this.width / 2.0,
+            this.y + this.height / 2.0
+        );
+    }
+}
+```
+
+## 属性
+**格式:**
+```typescript
+/** summary */
+```
+**说明:**
+* *summary*
+
+&emsp;&emsp;    简要说明。
+
+**风格:**
+* “/**”、简要说明与“*/”在同一行;
+* "/**"、简要说明与“*/”之间隔一个空格;
+* 域属性的注释写在域;
+* 没有域的属性,写在 get 操作上;
+* 没有 get 操作,写在 set 操作上;
+
+**示例:**
+```typescript{2,5,13}
+export class SRect {
+    /** 左上角坐标 */
+    leftTop: SPoint;
+
+    /** 矩形的 x 轴坐标 */
+    get x(): number {
+        return this.leftTop.x;
+    }
+    set x(value: number) {
+        this.leftTop.x = value;
+    }
+
+    /** 旋转中心点 */
+    private _org = new SPoint():
+    get org(): number {
+        return this._org;
+    }
+    set org(value: number) {
+        this._org = value;
+    }
+}
+```
+
+## 枚举
+**格式:**
+* 枚举类注释
+```typescript
+/**
+ * class-summary
+ *
+ * @author  author-text
+ */
+```
+* 枚举值注释
+```typescript
+/** value-summary */
+```
+
+**说明:**
+* *summary*
+
+&emsp;&emsp;    简要说明。
+
+* *author-text*
+
+&emsp;&emsp;    作者描述。描述要包含作者的姓名与邮箱地址。
+
+* *value-summary*
+
+&emsp;&emsp;    枚举值的简要说明。
+
+**风格:**
+* 枚举类注释见[类与接口注释](#类与接口注释);
+* “/**”、枚举值简要说明与“*/”在同一行;
+* "/**"、枚举值简要说明与“*/”之间隔一个空格;
+* 枚举值注释写在枚举值上;
+
+**示例:**
+```typescript{1-5,7,9,11}
+/**
+ * 手势状态
+ *
+ * @author  庞利祥 <sybotan@126.com>
+ */
+export enum STouchState {
+    /** 标准状态 */
+    None,
+    /** 移动状态 */
+    Move,
+    /** 缩放状态 */
+    Zoom,
+}
+```
+
+## 内部注释
+待定
+```typescript
+
+```

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

@@ -0,0 +1,4 @@
+# 排版
+::: details 目录
+[[toc]]
+:::

+ 53 - 0
docs/standard/typescript/naming.md

@@ -0,0 +1,53 @@
+# 命名
+::: details 目录
+[[toc]]
+:::
+
+## 标识符
+标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解——尽量采用采用英文单词或全部中文全拼表示。
+
+* 标识符只能使用字母,数字与“_”。
+* 首字符不能是数字;
+* 只有私有字段前缀使用“_”;
+* 全局常量的各单词间使用“_”分隔;
+
+## 大小写
+### 命名规范
+* **Pascal:**
+
+&emsp;&emsp;    将标识符的首字母和后面连接的每个单词的首字母都大写。
+
+* **Camel:**
+
+&emsp;&emsp;    标识符的首字母小写,而每个后面连接的单词的首字母都大写。
+
+* **Snake:**
+
+&emsp;&emsp;    标识符的每个单词都小写,单词间使用分隔符“_”分隔。
+
+### 大小写规范
+| 标识符       | 大小写   | 示例 |
+|:-----------:|:-------:|-------|
+| 命名空间     | Pascal   | namespace Sybotan {} |
+| 类          | Pascal   | export class SRect {} |
+| 接口        | Pascal   | export interface SICommandLog {} |
+| 函数        | Camel   | isEmpty(): boolean |
+| 属性        | Camel   | get left(): number |
+| 事件回调     | 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    | 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”前缀;
+* 所有的私有字段都加“_”前缀;