团队代码规范

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

此外,局部变量命名时避免跟全局变量重名,函数命名时避免跟内置函数名重名。

总之,名称应该具有意义,能让读者快速看懂其代表的内容。

函数

  • 一个函数只实现一个功能
  • 根据实现的功能取个合适的名称

results matching ""

    No results matching ""