通用编程规范

[AlexZ33]

通用编程规范

文件

1. 文件头应包含如下格式的版权声明，并与正文间隔一空行

   // Copyright 创建年份 alexz33

   # Copyright 创建年份  alexz33

2. 源文件行宽度不宜超过80字符宽度(说明: 对于服务器远程登录，笔记本等小屏友好)

命名规范

1. 一般仅限使用英文(除非是用户业务相关代码)，注意拼写正确性，不推荐使用复杂单词
2. 命名、日志等注意单次词性，动词名词不可混用
3. 变量名，metrics等保留单位，提高可读性，如kMaxFileSizeMB，latency_ms等

注释与文档

1. 从帮助读者理解代码的角度写注释(推荐写原理和背后的想法，不推荐些1+1=2这样的自解释注释)
2. 单词大小写要严谨，例如应使用TensorFlow(或tensorflow)而非Tensorflow，ReLU而非Relu，不限于代码注释，包含其他地方的文档
3. 代码中注释应为英文(除非是业务相关代码)，句首大写字母开头，注意排版

编程范式

1. 保持Fail-Fast编程，尽可能完备的检查(不影响关键路径性能)，尽可能早的Crash掉程序，并记录详细的信息
2. 原则上禁止使用全局非常量变量(适用于C/C++/Python等)

日志规范

1. 大写字母开头，注意语法，单次拼写正确，不推荐使用复杂单词
2. 考虑打印出来的格式是否便于阅读和grep过滤

测试

1. 项目应当具有足够的测试，且应输出量化的coverage，并达到一定数值
2. 单元测试的目的是测试代码在各种情况下的正确性，不能单纯为了提升coverage而添加test case (比如只执行代码，但不做任何校验，可以提升覆盖率，但用处有限)
3. 测试应适当添加Crash case的测试

分类编程规范

1. Python: PEP 8 -- Style Guide for Python Code
2. Shell: Google Shell Style Guide
3. C/C++: C/C++编程规范