团队代码规范
Documentation Strings ("docstrings")
在合作过程中,代码的可读性非常重要,所以在以下地方应该有docstrings
:
- 在模块文档的开头
- 在类定义的后面,说明这个类的作用
- 在函数定义的后面,说明这个函数的作用
docstrings
应该说明实现了什么功能 (what is being done),而非功能是怎样具体实现的 (how it is done)。
除了描述功能之外,函数的docstrings
还应该说明函数接受的参数(arguments)、返回的内容(return)和可能产生的副作用(side effects)。
docstrings
更详细的说明可查阅PEP 0257 -- Docstring Conventions
样例可参照:
注释
除了docstrings
以外,注释对于代码的可读性也非常重要。
注释以'#'开头的单行或多行文字,用于说明:
- 某段代码块是用来做什么的
- 为什么选择这种解决方案而不是其他的方案
缩进
使用4个空格作为缩进,而不要使用tab
命名
- 变量和函数名不使用大写字母,词之间用下划线
_
分割,如some_variable_name
- 类名称使用驼峰命名法,每个词以大写字母开头,词之间无分隔符,如
SomeClassName
- 常量名中全部字母都大写,如
THIS_IS_A_CONSTANT
- 私有变量和函数以
_
开头,如_private_func
此外,局部变量命名时避免跟全局变量重名,函数命名时避免跟内置函数名重名。
总之,名称应该具有意义,能让读者快速看懂其代表的内容。
函数
- 一个函数只实现一个功能
- 根据实现的功能取个合适的名称