代码规范

Posted 2021-02-20 xtl233

代码规范

Python部分代码规范

代码格式

缩进

• 统一使用 4 个空格进行缩进

行宽

每行代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ，但最长不得超过 120)理由：

• 这在查看 side-by-side 的 diff 时很有帮助
• 方便在控制台下查看代码
• 太长可能是设计有缺陷

引号

• 自然语言 使用双引号 "..."
  例如错误信息；很多情况还是 unicode，使用u"你好世界"
• 机器标识 使用单引号 ‘...‘
  例如 dict 里的 key
• 正则表达式 使用原生的双引号 r"..."
• 文档字符串 (docstring) 使用三个双引号 """......"""

空行

• 模块级函数和类定义之间空两行；
• 类成员函数之间空一行；
• 可以使用多个空行分隔多组相关的函数
• 函数中可以使用空行分隔出逻辑相关的代码

空格

• 在二元运算符两边各空一格[=,-,+=,==,>,in,is not, and]:
• 函数的参数列表中，,之后要有空格
• 函数的参数列表中，默认值等号两边不要添加空格
• 左括号之后，右括号之前不要加多余的空格
• 字典对象的左括号之前不要多余的空格
• 不要为对齐赋值语句而使用的额外空格

换行

Python 支持括号内的换行。这时有两种情况。

1. 第二行缩进到括号的起始处

2. 第二行缩进 4 个空格，适用于起始括号就换行的情形

命名规范

模块

• 模块尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况

类名

• 类名使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头
• 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.

函数

• 函数名一律小写，如有多个单词，用下划线隔开
• 私有函数在函数前加一个下划线_

变量名

• 变量名尽量小写, 如有多个单词，用下划线隔开
• 常量采用全大写，如有多个单词，使用下划线隔开

常量

• 常量使用以下划线分隔的大写命名

注释

块注释

• “#”号后空一格，段落件用空行分开（同样需要“#”号）

行注释

• 至少使用两个空格和语句分开，注意不要使用无意义的注释

文档注释

• 文档注释以 """ 开头和结尾, 首行不换行, 如有多行, 末行必需换行, 以下是Google的docstring风格示例
• 不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等
• 对函数参数、返回值等的说明采用numpy标准, 如下所示
• 文档注释不限于中英文, 但不要中英文混用
• 文档注释不是越长越好, 通常一两句话能把情况说清楚即可
• 模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释

html部分代码规范

• 使用正确的文档类型，文档类型声明位于HTML文档的第一行。
• 使用小写元素名HTML5 元素名可以使用大写和小写字母。本项目中均采用小写字母。
• 关闭所有HTML元素，在本项目中所有元素均要添加关闭标签。
• 使用小写属性名，在本项目中所有属性名均事情小写字母。
• 空格和等号，本项目中等号前后不添加空格。
• 空行和锁缩进，不无缘无故添加空行，比较短的代码间不要使用不必要的空行和缩进。

JS部分代码规范

• 命名规则，JS部分命名规则与Python部分命名规则相同。
• 空格与运算符，通常运算符 ( = + - * / ) 前后需要添加空格。
• 代码缩进，通常使用 4 个空格符号来缩进代码块。
• 对象规则：将左花括号与类名放在同一行；冒号与属性值间有个空格；字符串使用双引号，数字不需要；最后一个属性值后面不添加逗号；将右花括号独立放在一行，并以分号作为结束符号。
• 每行代码字符建议小于80个，便于阅读。