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

Python 编码规范 v 0.1

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

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

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

普遍性原则

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

缩进

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

    # 可以
    foo_bar(self, width, height, color='black', design=None, x='foo', emphasis=None,
            highlight=0)
    # 不好
    foo_bar(self, width, height, color='black', design=None, x='foo', emphasis=None,
                                        highlight=0)

字典内一层加一个缩进：

    dictionary = {
        "foo": 1,
        "long_name": {
            long_name_2
            ...
            }
        }

空格

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

    # 可以
    x == 1
    # 不好
    x<1

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

    # 可以
    def complex(real, imag=0.0): return magic(r=real, i=imag)
    # 不好
    def complex(real, imag = 0.0): return magic(r = real, i = imag)

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

空行

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

行长度

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

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

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

左花括号的位置

用 K&R 风格，左花括号不换行：

    # 可以
    foo = {
        long_dictionary_key:
            long_dictionary_value,
            ...
        }
    # 不好
    foo =
        {
            long_dictionary_key:
                long_dictionary_value,
                ...
        }

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

注释

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

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

模块注释

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

    """                                      __  __                       _   _          """
    """                                    |  \/  |                     | | | |          """
    """  _ __     ___  __      __          | \  / |   ___    _   _    __| | | |   ___    """
    """ | '_ \   / _ \ \ \ /\ / /          | |\/| |  / _ \  | | | |  / _  | | |  / _ \   """
    """ | | | | |  __/  \ V  V /           | |  | | | (_) | | |_| | | (_| | | | |  __/   """
    """ |_| |_|  \___|   \_/\_/  ________  |_|  |_|  \___/   \__,_|  \__,_| |_|  \___|   """
    """                                                                                  """
    """                                                                                  """
    """ Module Name: new_Moudle                                                          """
    """ Author: Luo Zhong-qi                                                             """
    """ Last modified: 2021-04-26                                                        """
    """ Description: Describing the moudle                                               """
    """                                                                                  """
    """ Dependencies: pyTorch, numpy==1.2                                                """
    """ Importing: from New_Moudle import NewMoudle                                      """
    """ Exported classes:                                                                """
    """     NewMoudle                                                                    """
    """ Exported functions:                                                              """
    """ a_public_function(arg)                                                           """

方法与函数注释

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

    def my_func(val, str):
        """
        Describing the function of this function.
        Args:
            val[Integer: 1-100]: The meaning of this value.
            str[String: length=10-20]: The meaing of this string.
        Returns:
            A dict mapping keys to the corresponding data.
            {'Serak': ('Rigel VII', 'Preparer'),
            'Zim': ('Irk', 'Invader'),
            'Lrrr': ('Omicron Persei 8', 'Emperor')}
        Raises:
            ValueError: An error occurred as the uneligible arguments.
        """
        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，请注上你的名字，以下是一个例子：

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

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

导入格式

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

每个导入应该独占一行：

    # 可以
    import os
    import sys
    # 不好
    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"。