Merge branch 'master' of https://github.com/cntehang/dev-docs

Author: liulang

backend/resources/swagger.jpg

@@ -0,0 +1,100 @@
+# Swagger-usage-guideline
+
+- swagger 文档应成为前端调用后端接口的手册，在此对 swagger 使用进行规范，方便前后端交互。
+
+## API 名称和说明
+
+- 在 Controller 中对外暴露的方法上加上如下注解
+
+```java
+@ApiOperation(value = "API名称", notes = "API说明")
+```
+
+- 若该 API 有需要指出的异常情况，则在 notes 中加以说明，如下：
+
+```java
+@ApiOperation(
+    value = "员工登陆",
+    notes = "根据用户名和密码进行登陆认证</br>"
+        + "code = 1: 密码错误</br>"
+        + "code = 2: 用户名不存在"
+    )
+```
+
+- 有一种对返回值的写法如下，其会将 code 视为 Http Status Code，并不适合我们的情况，故不采用
+
+```java
+  @ApiResponses(value = {
+      @ApiResponse(code = 1, message = "密码错误"),
+      @ApiResponse(code = 2, message = "用户名不存在")
+  })
+```
+
+
+
+## 请求参数说明
+
+- 参数若为类对象：
+
+  - 类名上需加如下注释，用于说明此对象参数的名称：
+
+  ```java
+  @ApiModel(value = "登陆信息")
+  ```
+
+  - 类中字段需在 @ApiModelProperty 注解中加如下说明：
+    - value：表示字段名
+    - example：表示该字段的示例值，在测试时很有帮助
+    - required: 若为必携带的参数，则为true
+  
+    ```java
+      @ApiModelProperty(value = "用户名，可以为手机/邮箱", example = "[email protected]", required = true)
+    ```
+
+- 若为普通参数：
+  - 在方法的请求参数前，与 @RequestParam并列
+
+  ```java
+  @ApiParam(value = “用户ID”, example = "1100020")
+  ```
+
+## 返回值说明
+
+- 与请求参数如出一辙
+- 暂未看到返回非对象的注解方法，不过返回非对象的情况很少，基本可以忽略
+
+## Sagger 配置类示例
+
+```java
+@Configuration
+@EnableSwagger2
+public class SwaggerConfig {
+
+  /**
+   * swagger配置
+   * @return swagger相关配置
+   */
+  @Bean
+  public Docket createRestApi() {
+    return new Docket(DocumentationType.SWAGGER_2)
+            .apiInfo(apiInfo())
+            .select()
+            .apis(RequestHandlerSelectors.basePackage("com.tehang.tmc.services.application.rest.front.corp"))
+            .paths(PathSelectors.any())
+            .build();
+  }
+
+  private ApiInfo apiInfo() {
+    return new ApiInfoBuilder()
+            .title("TMC Services")
+            .description("出行从未如此简单")
+            .contact(new Contact("TMC group", "https://www.teyixing.com", "[email protected]"))
+            .version("1.0")
+            .build();
+  }
+
+}
+```
+
+## Swagger 文档界面说明
+![swagger文档界面说明](./resources/swagger.jpg)

backend/swagger-usage-guideline.md

@@ -0,0 +1,107 @@
+# 程序员工作指南
+
+持续的、高质效的软件开发能力是现代企业的核心竞争力。用软件创造未来的程序员责任重大，任劳任怨。可是环顾四周，多数软件团队的研发能力相对计算机的巨大潜力和广泛的业务需求有巨大鸿沟，开发效率低，软件的质量令人忧伤。稍感安慰的是半个多世纪的编程历史积累了一些最佳实践（best practices)。遵守基于这些最佳实践的规则能大大改善程序员的工作效率。
+
+## 1 前提
+
+程序员的工作规则是基于如下的前提：
+
+1. 真实和持久的幸福源于和一群优秀的同事达成共识、接受挑战、创造和分享非凡价值。
+
+1. 软件就是业务，软件开发是不间断的持续过程，直到企业/程序员/用户的生命尽头。在心智和身体上都需要有长远准备。
+
+1. 每个程序员都是业务的驱动者，拥有推动业务需要的所有知情权、资源和权利。
+
+1. 每一行语句都会有 10 次以上的修改，可维护性是根本。
+
+1. Bug 不可避免，但是很丢人，严重的错误是灾难性的。
+
+1. 沟通合作、达成共识比想象的困难和必要，需要学习和建立机制。
+
+1. 小就是美，便于理解和重用。
+
+## 2 基本规则
+
+### 2.1 对每个错误需要回答怎么不再犯
+
+不再犯同样的错误是最有效的工作方法。
+
+### 2.2 每周 40 小时工作，20 小时学习
+
+清醒的头脑和不断学习是持续高效的基本保证。偶尔的冲刺可以用 20 小时的学习时间来工作，但是不应该成为常态。不鼓励熬夜，禁止每周工作超过 60 个小时。
+
+### 2.3 每周锻炼 4 次，每次 1 个小时以上
+
+体魄健康，头脑才灵。
+
+### 2.4 达成共识
+
+在业务和技术领域的决策、设计、代码等都有审查（review）。事关重要的都要达成共识 -- 经过大家充分讨论和理解优劣点。
+
+### 2.5 程序员是业务专家
+
+技术的目的是为了业务。熟悉业务和市场趋势才能创造最大价值。
+
+## 3 团队规则
+
+### 3.1 赋能个人
+
+每个人都可以看到做事所需要的业务和技术信息、代码、资源。可以参与所有层级的决策。必要时第一线可以调动全公司资源来达成目标。
+
+### 3.2 达成共识
+
+决策是集体智慧的结果。相关人员都有发言权并充分参与讨论，每个人都清晰理解决策的过程、利弊考量和结果。
+
+### 3.3 分享团队管理职责
+
+团队的沟通、进度更新、不重犯错的方法、业务的改善等等，都是每个人的责任。大家分享团队管理职责，轮流主持各种会议。团队的每个问题都是我的问题。
+
+### 3.4 认真的审核
+
+设计文档与代码的审核是高效的质量保证。同时也是学习和沟通的好机会。
+
+### 3.5 程序员参与产品设计并计划开发进度
+
+程序员是业务专家和实现者。值得信赖和激发最大潜力。
+
+### 3.5 持续编写相关技术文档
+
+开发过程中随时编写相关技术文档，包括软件设计文档，技术选型，最佳实践，常见问题等。这样便于维护和分享。
+
+### 3.6 提倡异步通信
+
+程序员被打断一次平均需要 20 分钟才能恢复高效工作状态。尽量采用短信、邮件、Bug 库、代码库事件等异步通信方式沟通或约定面对面交流时间。
+
+## 4 编码规则
+
+### 4.1 自动化的测试是开发编码的一部分
+
+没有自动测试的代码不算完成。自动化的测试为十次以上的重构带来至关重要的质量保证。
+
+### 4.2 持续重构
+
+看到需要改进的代码就立刻重构，目的是保持代码结构的清晰。大概编码的 20% 时间是用于重构的。反之，如果不良代码持续累积，系统变大之后发生质变，很可能无法正常工作或难以修改。同样的修复，后期维护成本是前期的数倍，而且影响更大更难控制。
+
+### 4.3 每个函数不要超过 10 条语句
+
+便于理解和重用。不超过 10 的规则也适用于一个目录不超过 10 个文件或其他类似可拆分的场合。
+
+### 4.4 大的功能需要先设计再编码
+
+对于稍微复杂的、费时超过一个工作日的功能，先写设计文档。这样通常更快而且质量更好。
+
+### 4.5 一个函数的所有语句都在单一抽象层(Single Level Abstraction)
+
+保持程序的结构清晰，而且也容易理解。
+
+### 4.6 重复一次以后再抽象
+
+不要一开始就预想各种使用场景来做抽象，低效而且误导。重复一次以后再抽象会更高效。
+
+### 4.7 软件文档和注释
+
+每个共用函数和模块都应该有相应 API 文档。源代码有适当的注释。
+
+### 4.8 软件运行日志（Log）是程序的一部份
+
+日志对运维和错误调试至关重要。其层级（Level）和相关信息需要仔细规划。

developer-working-guide.md

@@ -0,0 +1,28 @@
+# Angular Best Practices
+
+Here is a set of best practices using Angular
+
+## Forms
+
+As hinted by the offical Angular document, use the new Reactive Form, not Template Form. Template forms are asynchornous and event-driven. They are also not as flexible as reactive forms. Reactive fomrs have the following benefits:
+
+- Synchronous form controls are easier to unit test
+- Forms and models are closely aligned
+- Group form controls together at different levels using group and array.
+- Validate form controls at any level and dynamically
+
+Use the following style to create a form:
+
+```ts
+constructor(private formBuilder: FormBuilder) {}
+
+ngOnInit() {
+  this.createForm()
+}
+
+createForm() {
+  this.myForm = this.formBuilder.group(...)
+}
+```
+
+For most simple scenarios, use `FormBuilder` to create a form. For a complicated form, create `FormGroup` and `FormControl` directly.

frontend/angular-best-practices.md

@@ -0,0 +1,129 @@
+# Code Documentation
+
+All Angular-based projects use [CompoDoc](https://compodoc.app/) as code documentation tool to generate project document.
+
+## What to Document
+
+Document non-trivial modules, components, methods and important class memebers. Feel free to use Chinese, but please use English for technical terms.
+
+Use `/docs` folder for additional project documents such as design document, implementation explanation etc.
+
+Generate documents to `/dist/documentation` folder. The command is `npx compodoc -p tsconfig.json -n 'My App Documentation' --includes ./docs -d dist/documentation`.
+
+建议项目的开发、设计文档放到 `docs`目录下面。产生的文档统一输出到 `dist/documentation`目录。
+
+To see the output, use `-w -s -o` options with `compodoc`.
+
+## How to Write Document
+
+Compodoc uses JSDoc comments for documentation.
+
+### JSDoc Comments
+
+The documentation should use one of the following styles:
+
+```ts
+/**
+ * One line comment.
+ */
+
+/**
+ * First line followed by a blank line.
+ *
+ * Second line
+ */
+
+/**
+ * First line.
+ * Second line.
+ */
+```
+
+### JSDoc Tags
+
+The following tags are supported in CompoDoc. 注意参数的注释不要写数据类型。JSDoc 可以从函数声明得到。
+
+```ts
+/**
+ * A summary of the function。函数总结
+ * @param target  The target to process. 这里不用写参数类型。
+ * @returns The processed target number
+ */
+function processTarget(target: string): number
+
+/**
+ * 不用给下面的代码产生文档
+ * @ignore
+ */
+
+/**
+ * 参考相关的文档。
+ * see link {@link Todo}
+ * see link {@link Todo|TodoClass}
+ * see link [Todo]{@link Todo}
+ * see link [Google]{@link http://www.google.com}
+ * see link {@link http://www.apple.com|Apple}
+ * see link {@link https://github.com GitHub}
+ */
+
+/**
+ * Example usage。使用举例。
+ *
+ * @example
+ * <mwl-calendar-day-view
+ *     [viewDate]="viewDate"
+ *     [events]="events">
+ * </mwl-calendar-day-view>
+ */
+```
+
+### Routing Documentation
+
+CompoDoc requires a const of type `Routes`, that is a parameter of `RouterModule.forRoot()) to generate routing document. Following is an example:
+
+```ts
+const appRoutes: Routes = [
+  { path: 'about', component: AboutComponent },
+  { path: '', component: HomeComponent },
+]
+RouterModule.forRoot(appRoutes)
+```
+
+### Documentation of module and component
+
+每个项目有想过的设计文档和一些关键点的说明，放在 `docs`目录下面。
+
+Add a `.md` file to the module or component with the same file name (except `.ts`). For example, for `my.component.ts`, add a `my.component.md` to document it with a file.
+
+### Additional documentation
+
+Adding additional markdown document files in a folder named `docs`. Then add a `summary.json` file as the following to give the structure of the additonal files:
+
+```json
+[
+  {
+    "title": "A TITLE",
+    "file": "a-file.md"
+  },
+  {
+    "title": "A TITLE",
+    "file": "a-file.md",
+    "children": [
+      {
+        "title": "A TITLE",
+        "file": "a-sub-folder/a-file.md"
+      }
+    ]
+  }
+]
+```
+
+Use `--includes` flag to include the addtional files in the final documentation.
+
+## Resources
+
+- [CompoDoc Website](https://compodoc.app/)
+- [A Live Demo](https://compodoc.github.io/compodoc-demo-todomvc-angular/)
+- [The Live Demo Source Code](https://github.com/compodoc/compodoc-demo-todomvc-angular)
+- [A tutorial of an Ionic project](https://compodoc.app/guides/tutorial.html)
+- [Another video tutorial](https://youtu.be/90lnNtPmL8Y)

frontend/code-documentation.md

@@ -31,7 +31,7 @@ The following are some commons user settings for VS Code IDE.
 
 ### 常用的 Extensions
 
-- [Angular 6 Snippets](https://marketplace.visualstudio.com/items?itemName=Mikael.Angular-BeastCode): TypeScript, HTML, Angular Material, RxJS 等的 snippets.
+- [Angular 6 Snippets](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2): TypeScript and HTML 的 snippets.
 - [Bracket Pair Colorizer](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer): 给予匹配的括号`()`, `{}`, `[]`不同颜色。
 - [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome): a debug tool for Chrome.
 - [Kary Pro Colors](https://marketplace.visualstudio.com/items?itemName=karyfoundation.theme-karyfoundation-themes): 配置主题和颜色。

frontend/frontend-project-guideline.md

@@ -46,6 +46,10 @@ The coding guidelines are defined in the next section. There are two tools used
 1. When stating a rule, the subject should be in the singular (e.g. "An external module cannot..." instead of "External modules cannot...").
 1. Use present tense.
 
+### 2.6 Angular and others
+
+The Google Angular team has [a style guide](https://angular.io/guide/styleguide) that has many rules applicable for other front end develpment. Some useful rules include naming, small functions, single responsible principle, filename and etc.
+
 ## 3 TS Compiler Options
 
 First of all, set the following compiler options in `tsconfig.json` to enforce strict type checking and error detection.