python代码规范整理

规范参考源：

1.pep8（python代码样式规范）：中文文档      https://blog.csdn.net/ratsniper/article/details/78954852

2.pep257(python文档字符串相关约定)：文档地址    https://github.com/qiuxiang/pep/blob/master/peps/257.md

3.pep20(python的禅宗) ：文档地址  https://www.python.org/dev/peps/pep-0020/

 

代码样式规范（pep8）：

1、行缩进：tap键（4个空格）

隐式行连接缩进：

1.对齐缩进

foo = long_function_name(var_one,var_two,
　　　　　　　　　　　　　　 var_three, var_four,var_five)

2.层级缩进

def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

3. \

with open('test1.txt','w') as f1, \
     open('test2.txt','w') as f2;
    f1.write('hello')
    f2.write('python')

2.单行字符限制：

1.所有行限制的最大字符数为79；

2.没有结构化限制的大块文本（文档字符或注释）；

每行最大字符数限制在72，可根据需要调整，建议不超过100

3.空行：

顶级函数与类的定义之间有两行空行。

类顶部的函数定义之间有一行空行。

4.源文件编码方式：

python核心发布的代码中应该自始至终使用UTF-8（python2默认是ASCII编码）

python3种不应有编码声明

5.注释

与代码相矛盾的注释比没有注释还糟，当代吗更改时，优先更新对应的注释；

如果注释很短，结尾句号可以省略。块注释一般由一个完整的句子或多个段落组成，并且每句结束有句号，在句号结束的时候应该使用两个空格

在非英语国家的python程序员，请使用英文写注释，除非你120%的确信你的代码不会被使用其他语言的人阅读

行内注释：

#与代码间至少要有两个空格分隔，注释由#和一个空格开始。有节制地使用行内注释

response=requests.get('https://www.baidu.com')  # 请求百度首页

块注释

通常用于跟随它们的某些或全部代码，并缩进到与代码相同的级别。块注释的每一行开头使用一个#和一个空格（除非块注释内部缩进文本）。

块注释内部的段落通常只有一个#的空行分隔。

def add_num(a,b,c):
    # 此函数的作用为打印a，b，c三个数相加之和，并返回
    #
    # 通过format进行格式化输出结果
    print（'三个数相加的结果｛｝'.format(a+b+c)）

PEP257

文档注释（文档说明）：PEP257描述了写出好的文档说明相关的约定。

文档注释应当使用：常用3个双引号"""quotes"""来包裹

要为所有的公共模块，函数，类，以及方法编写文档说明。

非公共的方法没有必要添加注释文档，但是应该有一个描述方法具体作用的注释。这个注释应该在def那一行之后

def get(url, params=None, **kwargs):
    r"""Sends a GET request.

    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary, list of tuples or bytes to send
        in the query string for the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response <Response>` object
    :rtype: requests.Response
    """

    kwargs.setdefault('allow_redirects', True)
    return request('get', url, params=params, **kwargs)

单行文档注释："""quote""" ，一个简短的句子，引号和文字在同一行

多行文档注释：多行文档字符串有一个摘要组成，就像一行文档字符串，后跟一个空行，后面是更详细的描述，多行文档说明使用的结尾三引号应该自成一行

提取文档注释：对象的__doc__属性

import requests
print(requests.__doc__)
print(requests.get.__doc__)

6、模块和包相关规范

导入代码位置：导入常常位于文件顶部，在文档字符串（注释）之后，在模块的全局变量和常量之前

导入顺序分组：

1.标准库导入

2.相关的第三方库导入

3.特定的本地应用/库导入，

推荐:      import os
          import sys
不推荐:    import sys, os
允许：     from subprocess import Popen, PIPE
推荐绝对路径：from mypkg.sibling import example
允许相对路径：from . import sibling
            from .sibling import example

4.__all__ , __author__ , __version__ 等这样的模块级内置属性，应该放在文档字符串的后面，以及除from __future__ 之外的import表达式前面。

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

7、命名规范

变量命名

永远不要使用字母‘l’（小写的L），‘O’（大写的O），或者‘I’（大写的I）作为单字符变量名。 
在有些字体里，这些字符无法和数字0和1区分，如果想用‘l’，用‘L’代替。

函数命名

函数名应该小写，如果想提高可读性可以用下划线分隔。 
大小写混合仅在为了兼容原来主要以大小写混合风格的情况下使用（比如 threading.py），保持向后兼容性。

包名或模块名

模块应该用简短全小写的名字，如果为了提升可读性，下划线也是可以用的。Python包名也应该使用简短全小写的名字，但不建议用下划线。 

类名

类名一般使用首字母大写的约定。 
在接口被文档化并且主要被用于调用的情况下，可以使用函数的命名风格代替。 
注意，对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词（或者两个单词连接在一起），首字母大写的命名法只用于异常名或者内部的常量。

 类里面的函数与方法参数

始终要将 self 作为实例方法的的第一个参数。 
始终要将 cls 作为类静态方法的第一个参数。 
如果函数的参数名和已有的关键词冲突，在最后加单一下划线比缩写或随意拼写更好。因此 class_ 比 clss 更好。（也许最好用同义词来避免这种冲突）

常量

常量通常定义在模块级，通过下划线分隔的全大写字母命名。例如： MAX_OVERFLOW 和 TOTAL。

 

最后附上python之禅中文版：

优美胜于丑陋（Python 以编写优美的代码为目标）

明了胜于晦涩（优美的代码应当是明了的，命名规范，风格相似）

简洁胜于复杂（优美的代码应当是简洁的，不要有复杂的内部实现）

复杂胜于凌乱（如果复杂不可避免，那代码间也不能有难懂的关系，要保持接口简洁）

扁平胜于嵌套（优美的代码应当是扁平的，不能有太多的嵌套）

间隔胜于紧凑（优美的代码有适当的间隔，不要奢望一行代码解决问题）

可读性很重要（优美的代码是可读的）

即便假借特例的实用性之名，也不可违背这些规则（这些规则至高无上）