[comment]添加CONTRIBUTING.md,包含一些注释相关的建议

This commit is contained in:
cgj 2023-12-28 17:35:46 +08:00
parent 210baeec9f
commit b026ca8786
1 changed files with 53 additions and 0 deletions

53
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,53 @@
## 代码注释
为提高代码的可读性,我们希望你能按照以下几条规则编写注释,
- 核心:```不要解释是什么,而是回答为什么```
- 统一的注释风格
``` tsx
/**
* 这是块级注释
*/
// 这是行内注释
//============================== 分隔符 ==============================
```
- 注释不要重复代码内容
``` tsx
// 注释和代码含义相同,无需添加
// error是个promise
if (isPromise(error)) {
...
}
```
- 注释不要解释模糊代码
``` tsx
// 最佳节点
let n: Node | null = null;
```
直接在代码中通过名称表达清楚,可以省略掉注释
``` tsx
let bestNode: Node | null = null;
```
如果添加注释则是补充性的额外信息
```tsx
// 全局指针,在遍历时指向当前最佳的节点
let bestNode: VNode | null = null;
```
- 巧妙或复杂的代码要添加注释解释逻辑
- 对所有导出的顶层模块进行注释
- 注释应该是直接的,不要有不明确的表达或符号