[关闭]
@Bei-S 2021-07-22T01:52:51.000000Z 字数 4165 阅读 104

=====================================

Python 编码规范 v 0.1

=====================================

为了使代码更加简明、优雅、易读、易维护,统一代码风格,请采用如下建议进行编码。
更多可参考 PEP-8 : https://www.python.org/dev/peps/pep-0008/

=====================================

普遍性原则

=====================================

缩进

使用4个空格缩进代码,不使用 TAB 。
对于行连接的情况,使得下一行与同圆括号内变量起始处对齐:

  1. # 可以
  2. foo_bar(self, width, height, color='black', design=None, x='foo', emphasis=None,
  3. highlight=0)
  4. # 不好
  5. foo_bar(self, width, height, color='black', design=None, x='foo', emphasis=None,
  6. highlight=0)

字典内一层加一个缩进:

  1. dictionary = {
  2. "foo": 1,
  3. "long_name": {
  4. long_name_2
  5. ...
  6. }
  7. }

空格

运算符两侧都应加空格,如赋值(=),比较(==, <, >, !=, <>, <=, >=, in, not in, is, is not),布尔(and, or, not),数学运算(+, -)等

  1. # 可以
  2. x == 1
  3. # 不好
  4. x<1

逗号、冒号、分号后应加空格,但在行尾时不加。
当 '=' 用于指示关键字参数或默认参数值时,不要在其两侧使用空格:

  1. # 可以
  2. def complex(real, imag=0.0): return magic(r=real, i=imag)
  3. # 不好
  4. def complex(real, imag = 0.0): return magic(r = real, i = imag)

括号、引号内部不加空格。

空行

顶级定义之间空两行,比如函数或者类定义。
方法定义,类定义与第一个方法之间,都应该空一行。
方法或函数中,比较大的步骤间空一行。

行长度

每行不超过80个字符,不包括空格:

  1. # 对于较多函数调用的参数,在逗号后换行
  2. foo_bar(self, width, height, color='black', design=None, x='foo', emphasis=None,
  3. highlight=0)
  4. # 对于长的复合表达式,在与或运算符后换行
  5. if (width == 0 and height == 0 and color == 'red' and emphasis == 'strong' and
  6. highlight == 0):

以下情况除外:
1. 头注释;
2. 长的导入模块语句;
3. 较长的常量字符串,如 URL 等。

左花括号的位置

K&R 风格,左花括号不换行:

  1. # 可以
  2. foo = {
  3. long_dictionary_key:
  4. long_dictionary_value,
  5. ...
  6. }
  7. # 不好
  8. foo =
  9. {
  10. long_dictionary_key:
  11. long_dictionary_value,
  12. ...
  13. }

=====================================

注释

=====================================

注释尽可能使用 ASCII 字符书写,以免出现编码问题。更详细的可参见 Pydoc: https://docs.python.org/3/library/pydoc.html

模块注释

每个模块都应在最开始加上一个头注释,由以下部分组成:
1. ASCII Art 格式的包名;
2. 模块名;
3. 模块的参与作者;
4. 模块最后一次的修改日期
5. 模块的功能描述;
6. 依赖的外部库;
7. 模块的引入方法;
8. 模块开放出的类与函数。
以下是一个例子(Markdown 中缩进才是代码环境,实际不应缩进):

  1. """ __ __ _ _ """
  2. """ | \/ | | | | | """
  3. """ _ __ ___ __ __ | \ / | ___ _ _ __| | | | ___ """
  4. """ | '_ \ / _ \ \ \ /\ / / | |\/| | / _ \ | | | | / _ | | | / _ \ """
  5. """ | | | | | __/ \ V V / | | | | | (_) | | |_| | | (_| | | | | __/ """
  6. """ |_| |_| \___| \_/\_/ ________ |_| |_| \___/ \__,_| \__,_| |_| \___| """
  7. """ """
  8. """ """
  9. """ Module Name: new_Moudle """
  10. """ Author: Luo Zhong-qi """
  11. """ Last modified: 2021-04-26 """
  12. """ Description: Describing the moudle """
  13. """ """
  14. """ Dependencies: pyTorch, numpy==1.2 """
  15. """ Importing: from New_Moudle import NewMoudle """
  16. """ Exported classes: """
  17. """ NewMoudle """
  18. """ Exported functions: """
  19. """ a_public_function(arg) """

方法与函数注释

所有外部可见的方法和函数、生成器都应增加函数注释,直接置于函数定义的 def 语句下方。
函数、方法与生成器的注释应包括函数会做什么,以及输入与输出的详细描述,使得调用者无需阅读一行代码就可以调用该函数。
函数的注释应包括下面几个部分:
1. 功能描述(description):简述函数的功能;
2. 参数(Args):列出每个参数的名称与期望的格式或类型,后接对该参数意义或详细格式的描述;
3. 返回值(Returns):列出返回值的类型、格式与意义;
4. 异常(Raises):列出与接口相关的异常。
以下是一个例子:

  1. def my_func(val, str):
  2. """
  3. Describing the function of this function.
  4. Args:
  5. val[Integer: 1-100]: The meaning of this value.
  6. str[String: length=10-20]: The meaing of this string.
  7. Returns:
  8. A dict mapping keys to the corresponding data.
  9. {'Serak': ('Rigel VII', 'Preparer'),
  10. 'Zim': ('Irk', 'Invader'),
  11. 'Lrrr': ('Omicron Persei 8', 'Emperor')}
  12. Raises:
  13. ValueError: An error occurred as the uneligible arguments.
  14. """
  15. pass

类注释

所有开放的类应该在其定义下有一个用于描述该类的文档字符串。如果你的类有公共属性(Attributes),那么文档中应该有一个属性(Attributes)段,另外其中开放的函数也应加上函数注释。
'''
class SampleClass(object):
"""
Summary of class here.

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

'''

一般注释

复杂的算法与操作应加上单行注释,以提示步骤。
重要的变量与常量直接在其定义后空一格加上注释。
'''
A_VERY_IMPORTANT_CONSTANT = "AAAAA" # The description of this constant
'''

TODO注释

TODO注释应该在所有开头处包含"TODO"字符串, 紧跟着是用括号括起来的你的名字,接着必须有一行注释,解释要做什么。
写了TODO注释并不保证写的人会亲自解决问题,当你写了一个TODO,请注上你的名字,以下是一个例子:

  1. # TODO(Luo Zhongqi): Wait for realizing this function...

=====================================

导入格式

=====================================

每个导入应该独占一行:

  1. # 可以
  2. import os
  3. import sys
  4. # 不好
  5. import os, sys

导入总应该放在文件顶部,位于模块注释之后,模块全局变量和常量之前,按照从最通用到最不通用的顺序分组:
1. 标准库导入;
2. 第三方库导入;
3. 自定义库导入。

=====================================

全局变量与常量

=====================================

所有的全局变量、常量、枚举置于导入之后,重要的、需要常修改的参数尽量不写成常量。

=====================================

命名

=====================================

模块名

模块使用大驼峰命名法(Upper Camel Case)加下划线命名,如:"foo_Bar"。

包名

包使用大驼峰命名法(Upper Camel Case)加下划线命名,如:"foo_Bar"。

类名

类使用大驼峰命名法(Upper Camel Case),即大写字母无下划线,如:"FooBar"。

方法与函数名

方法与函数使用小写字母加下划线命名,如:"foo_bar()"。

变量名

变量名使用小驼峰命名法(Lower Camel Case),即小写字母开头,后每一个词首字幕用大写,如:"fooBar"。
类的示例对象名和变量名一致。

参数名

参数名使用小写字母简写,如:"fbar", "cval"。

错误名

错误名与类名一致。

常量与枚举成员名

常量与枚举成员使用全大写加下划线命名,如:"FOO_BAR"。

临时变量名

临时变量采用简写或常用的单字符,如:"i", "j"。

添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注