diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..46d6888f --- /dev/null +++ b/CONTRIBUTING.md @@ -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; + ``` + +- 巧妙或复杂的代码要添加注释解释逻辑 + +- 对所有导出的顶层模块进行注释 + +- 注释应该是直接的,不要有不明确的表达或符号