Skip to content

Commit 0248214

Browse files
author
ying.liu
committed
refact dev documents
1 parent c871fb3 commit 0248214

20 files changed

+135
-108
lines changed
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

frontend/angular-best-practices.md

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,24 @@
11
# Angular Best Practices
22

3-
Here is a set of best practices using Angular
3+
Here is a set of best practices using Angular.
44

5-
## Forms
5+
## Constructor and Lifecycle Hooks
6+
7+
For property bindings and change detection theories, check [these blogs](https://blog.angularindepth.com/these-5-articles-will-make-you-an-angular-change-detection-expert-ed530d28930).
8+
9+
Simply, follow the following rules:
10+
11+
- Use `constructor()` only for dependency injection.
12+
- Use `ngOninit()` to initialize data-bound properties.
13+
- Use `ngAfterViewInit()` when you need to do something after the component view is initialized. The `@ViewChild` fields are initialized when this hook is called.
14+
- Use `ngDestroy()` to clear resources such as unsubscribing from observables.
15+
- Use asynchronous methods to update properties and know the `NgZone` concept to avoid the `ExpressionChangedAfterItHasBeenCheckedError` error.
616

7-
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:
17+
## Forms
818

9-
- Synchronous form controls are easier to unit test
10-
- Forms and models are closely aligned
11-
- Group form controls together at different levels using group and array.
12-
- Validate form controls at any level and dynamically
19+
Only use the reactive Form, not Template Form. Template forms are asynchornous and event-driven. They are also not as flexible as reactive forms.
1320

14-
Use the following style to create a form:
21+
For most simple scenarios, use `FormBuilder` to create a form. For a complicated form, create `FormGroup` and `FormControl` directly.
1522

1623
```ts
1724
constructor(private formBuilder: FormBuilder) {}
@@ -25,12 +32,16 @@ createForm() {
2532
}
2633
```
2734

28-
For most simple scenarios, use `FormBuilder` to create a form. For a complicated form, create `FormGroup` and `FormControl` directly.
35+
一些建议:
36+
37+
- 针对复杂表单(表单项的验证规则是可变的情况),使用 `from.valid/invalid` 判断时,需要注意是否是最新的状态,因为可能某个表单项改变了验证规则,但是没有更新.
38+
- 对于大范围改变表单验证规则的情况,可以考虑重新 init form, 但需要小心(注意 html 中需要用 ngif 把不需要的表单 remove 掉).
39+
- 把定义和获取 control 的代码放到最后 `get controlName() { return this.form.get('controlName')}`, 以更方便 review .
40+
- 如果一个验证规则被重复多次使用,请使用类似 `const pattern = Validators.pattern(moneyRegex)` ,让代码变得更简洁.
41+
- 表单 `control` 统一使用 `touched` 进行错误提示。
2942

3043
## Dependency Injection
3144

32-
- Use `providedIn: 'root'` for services which should be available in whole application as singletons.
33-
- Never use `providedIn: EagerlyImportedModule`, you don’t need it and if there is some super exceptional use case then go with the `providers: []` instead.
34-
- Use `providedIn: LazyServiceModule` to prevent service injection in the eagerly imported part of the application. Use `LazyServiceModule` which will be imported by `LazyModule` to prevent circular dependency warning. LazyModule will then be lazy loaded using Angular Router for some route in a standard fashion. This is not recommended for too much confusing code.
35-
- Use `providers: []` inside of `@Component` or `@Directive` to scope service only for the particular component sub-tree which will also lead to creation of multiple service instances (one service instance per one component usage)
36-
- Always try to scope your services conservatively to prevent dependency creep and resulting tangled hell
45+
- Use `providedIn: 'root'` for all services which should be available as singletons.
46+
- Use file structure to scope services. A module can only use services that are in its subfoler or share the same parent folder.
47+
- Use `providers: []` for services that 1) need initialization (such as `myService.forRoot()`) or 2) inside `@Component` or `@Directive` for scoped mulitple-instance services.

frontend/code-documentation.md renamed to frontend/code-standards/code-documentation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ To see the output, use `-w -s -o` options with `compodoc`.
1616

1717
## How to Write Document
1818

19-
Compodoc uses JSDoc comments for documentation.
19+
Compodoc uses JSDoc comments for documentation. 建议使用 VS Code 插件 [`document this`](https://marketplace.visualstudio.com/items?itemName=joelday.docthis) 进行代码注释。
2020

2121
### JSDoc Comments
2222

File renamed without changes.

frontend/frontend-project-guideline.md renamed to frontend/ide-setup.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ The following are some commons user settings for VS Code IDE.
4343
- [TSLint](https://marketplace.visualstudio.com/items?itemName=eg2.tslint): TypeScript 代码检查工具。和 Preettier 一起用。具体配置参考代码标准文档。
4444
- [TypeScript Hero](https://marketplace.visualstudio.com/items?itemName=rbbit.typescript-hero): 管理排列`imports`
4545
- [vscode-icons](https://marketplace.visualstudio.com/items?itemName=robertohuertasm.vscode-icons): 各种文件 Icon。
46+
- [document this](https://marketplace.visualstudio.com/items?itemName=joelday.docthis): 生成代码注释。
4647

4748
### 命令行运行 VS Code
4849

0 commit comments

Comments
 (0)