Signed-off-by: Wu Fengguang wfg@mail.ustc.edu.cn --- doc/code-spec.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)

diff --git a/doc/code-spec.md b/doc/code-spec.md index d405cdd..52af5e6 100644 --- a/doc/code-spec.md +++ b/doc/code-spec.md @@ -2,12 +2,18 @@ code注意事项 ============

- 代码应当放进函数里 不要在脚本顶层直接写逻辑 + - 代码应当放进lib/里 脚本本身最小化, 仅解析命令行参数, 调用lib/入口函数 + - 如果出现了全局变量 一般意味着需要写一个 class/module 来放这个状态量了 + - 一个函数, 不要超过10行代码, 该原则适用于所有ruby/crystal/shell各类程序. + - 起准确和有意义的变量/函数名字, 名字要让人看出赋予他们的确切意义 + - 函数要有分层结构. 每个函数须有明确的定位: 业务层逻辑, 还是底层支持性routine. 一个函数不能同时做两个层次的事. 同一函数内避免混杂不同类型的事务. + - 如果注释仅仅是代码的简单重复, 不提供额外信息量, 不要写.

重构友好编码 @@ -31,6 +37,7 @@ PATCH注意事项 =============

- PATCH title 应当简要说明做了什么 (what) + - PATCH changelog / code comment 应当解释读者无法从代码简单推断的 - 背景 - 目的 @@ -39,9 +46,18 @@ PATCH注意事项 - 实际例子 - 改进数字 - bug场景, 出错消息原文 + - PATCH 应当加上作者签名 (Signed-off-by: Name <email>) + - PATCH 最好不超过100行, 一个PATCH只做一件事, 避免混杂多个逻辑变更

+- changelog/comment里的话，需理顺逻辑关系，让人一看就知道在讲什么， + 比如问题、原因、条件、结果、预期、假设、场景、目的、副作用、权衡， + 哪些是因果关系，哪些是可能，哪些是肯定。 + +- 论述问题的时候，引用必要的代码或output，帮助明确逻辑流/数据流。 + 引文加TAB缩进显示。 + PATCH参考材料 =============