python-代码规范-命名规范

发表于 | in | | 访客

时间久了，一些不长用的就慢慢忘记了，这里重新记录一下所有的规范，加强记忆

代码格式

空行

  • 模块级函数和类定义之间空两行
  • 类和类之间空两行
  • 类成员函数之间空一行
  • 类与import之间空两行
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    import os
    class A(object): # 两行
      
        def __init__(self):
            pass
        def say(self): # 一行
            pass
    class B(object): # 两行
        def __init__(self):
            pass
    def main(): # 两行
        pass

编码

使用utf-8编码,在模块文件头部：

1
#-*- coding:utf-8 -*-

import 语句

  • import 语句分行写，不要一次引入多个包
  • import语句应该放在文件头部，置于模块说明及docstring之后，于全局变量之前
    1
    2
    3
    4
    5
    6
    7
    # 正确写法
    import json
    import os
    from yaml import MappingNode, SequenceNode
    # 不推荐写法
    import os, yaml

空格

  • 在二元运算符两边各空一格[=,-,+=,==,>,in,is not, and]:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    # 正确的写法
    i = i + 1
    submitted += 1
    x = x * 2 - 1
    hypot2 = x * x + y * y
    c = (a + b) * (a - b)
     
    # 不推荐的写法
    i=i+1
    submitted +=1
    x = x*2 - 1
    hypot2 = x*x + y*y
    c = (a+b) * (a-b)

  • 函数的参数列表中，,之后要有空格

    1
    2
    3
    4
    5
    6
    7
    # 正确的写法
    def complex(real, imag):
        pass
         
    # 不推荐的写法
    def complex(real,imag):
        pass

  • 函数的参数列表中，默认值等号两边不要添加空格

    1
    2
    3
    4
    5
    6
    7
    # 正确的写法
    def complex(real, imag=0.0):
        pass
         
    # 不推荐的写法
    def complex(real, imag = 0.0):
        pass

换行

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

    1
    2
    foo = long_function_name(var_one, var_two,
                             var_three, var_four)

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

    1
    2
    3
    4
    def long_function_name(
            var_one, var_two, var_three,
    	var_four):
        print(var_one)

  • 使用反斜杠\换行，二元运算符+ .等应出现在行末；长字符串也可以用此法换行

    1
    2
    3
    4
    5
    6
    7
    session.query(MyTable).\
            filter_by(id=1).\
            one()
     
    print 'Hello, '\
          '%s %s!' %\
          ('Harry', 'Potter')

  • 禁止复合语句，即一行中包含多个语句

    1
    2
    3
    4
    5
    6
    7
    # 正确的写法
    do_first()
    do_second()
    do_third()
     
    # 不推荐的写法
    do_first();do_second();do_third();

  • if/for/while一定要换行

    1
    2
    3
    4
    5
    6
    # 正确的写法
    if foo == 'blah':
        do_blah_thing()
     
    # 不推荐的写法
    if foo == 'blah': do_blash_thing()

docstring

docstring 的规范中最其本的两点：

  • 所有的公共模块、函数、类、方法，都应该写 docstring 。私有方法不一定需要，但应该在 def 后提供一个块注释来说明
  • docstring 的结束”””应该独占一行，除非此 docstring 只有一行
    1
    2
    3
    4
    5
    """Return a foobar
    Optional plotz says to frobnicate the bizbaz first.
    """
     
    """Oneline docstring"""

注释

块注释

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

1
2
3
4
5
# 块注释
# 块注释
#
# 块注释
# 块注释

行注释

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

1
2
3
4
5
# 正确的写法
x = x + 1  # 边框加粗一个像素
 
# 不推荐的写法(无意义的注释)
x = x + 1 # x加1

建议

  • 在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释
  • 比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性
    1
    2
    3
    4
    5
    6
    7
    8
    app = create_app(name, options)
     
    # =====================================
    # 请勿在此处添加 get post等app路由行为 !!!
    # =====================================
    if __name__ == '__main__':
        app.run()

文档注释(Docstring)

作为文档的Docstring一般出现在模块头部、函数和类的头部，这样在python中可以通过对象的doc对象获取文档.
编辑器和IDE也可以根据Docstring给出自动提示.

  • 文档注释以 “”” 开头和结尾, 首行不换行, 如有多行, 末行必需换行, 以下是Google的docstring风格示例

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    # -*- coding: utf-8 -*-
    """Example docstrings.
    This module demonstrates documentation as specified by the `Google Python
    Style Guide`_. Docstrings may extend over multiple lines. Sections are created
    with a section header and a colon followed by a block of indented text.
    Example:
        Examples can be given using either the ``Example`` or ``Examples``
        sections. Sections support any reStructuredText formatting, including
        literal blocks::
            $ python example_google.py
    Section breaks are created by resuming unindented text. Section breaks
    are also implicitly created anytime a new section starts.
    """

  • 不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等

    1
    2
    3
    4
    5
    6
    7
    8
    9
    #  不推荐的写法(不要写函数原型等废话)
    def function(a, b):
        """function(a, b) -> list"""
        ... ...
     
    #  正确的写法
    def function(a, b):
        """计算并返回a到b范围内数据的平均值"""
        ... ...

  • 对函数参数、返回值等的说明采用numpy标准, 如下所示

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    def func(arg1, arg2):
        """在这里写函数的一句话总结(如: 计算平均值).
        这里是具体描述.
        参数
        ----------
        arg1 : int
            arg1的具体描述
        arg2 : int
            arg2的具体描述
        返回值
        -------
        int
            返回值的具体描述
        参看
        --------
        otherfunc : 其它关联函数等...
        示例
        --------
        示例使用doctest格式, 在`>>>`后的代码可以被文档测试工具作为测试用例自动运行
        >>> a=[1,2,3]
        >>> print [x + 3 for x in a]
        [4, 5, 6]
        """

  • 文档注释不限于中英文, 但不要中英文混用

  • 文档注释不是越长越好, 通常一两句话能把情况说清楚即可
  • 模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释

命名规范

模块

  • 模块尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况)
    1
    2
    3
    4
    5
    6
    # 正确的模块名
    import decoder
    import html_parser
     
    # 不推荐的模块名
    import Decoder

类名

  • 类名使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    class Farm():
        pass
     
    class AnimalFarm(Farm):
        pass
    class _PrivateFarm(Farm):
        pass

  • 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.

函数

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

    1
    2
    3
    4
    5
    6
    def run():
        pass
     
    def run_with_env():
        pass
    ```

  • 私有函数在函数前加一个下划线_

    1
    2
    3
    4
    class Person():
     
        def _private_func():
            pass

变量名

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

    1
    2
    3
    if __name__ == '__main__':
        count = 0
        school_name = ''

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

    1
    2
    3
    MAX_CLIENT = 100
    MAX_CONNECTION = 1000
    CONNECTION_TIMEOUT = 600