python编码规范手册

目录
一、编码	2
二、行长度	2
三、引号	2
四、空行	2
五、import 语句	2
六、 注释	3
6.1、块注释	3
6.2、行注释	3
6.3、文档注释	4
七、 命名规范	5
7.1、模块	5
7.2、类名	5
7.3、函数	5
7.4、变量名	6
7.5、常量名	6

一、编码
1.1、如无特殊情况，文件一律使用UTF-8编码。
1.2、如无特殊情况，文件头部必须加入#--coding:utf-8--标识。

二、行长度
2.1、每行代码尽量不超过80个字符(在特殊情况下可以略微超过80，但最长不得超过120)

三、引号
3.1、正则表达式，使用原生的双引号 r"…"
3.2、文档字符串，使用三个双引号 “”"…"""

四、空行
模块级函数和类定义之间空两行；类成员函数之间空一行；可以使用多个空行分隔多组相关的函数，函数中可以使用空行分隔出逻辑相关的代码。

class A:

def __init__(self):
    pass

def hello(self):
    pass

def main():
pass

五、import 语句

import语句应该分行书写

# 正确的写法
import os
import sys

# 不推荐的写法
import sys,os

六、注释
6.1、块注释

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

# 块注释
# 块注释
#
# 块注释
# 块注释

6.2、行注释

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

# 正确的写法
x = x + 1  # 边框加粗一个像素

# 不推荐的写法(无意义的注释)
x = x + 1 # x加1

在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释

比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性

app = create_app(name, options)

# =====================================
# 请勿在此处添加 get post等app路由行为 !!!
# =====================================

if __name__ == '__main__':
    app.run()

6.3、文档注释

作为文档的注释一般出现在模块头部、函数和类的头部。文档注释以 “”" 开头和结尾, 首行不换行, 如有多行, 末行必需换行,不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等

#  不推荐的写法(不要写函数原型等废话)
def function(a, b):
    """function(a, b) -> list"""
    ... ...

#  正确的写法
def function(a, b):
    """计算并返回a到b范围内数据的平均值"""
    ... ...

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

def func(arg1, arg2):
“”"在这里写函数的一句话总结(如: 计算平均值).

这里是具体描述.

参数
----------
arg1 : int
    arg1的具体描述
arg2 : int
    arg2的具体描述

返回值
-------
int
    返回值的具体描述

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

七、命名规范
7.1、模块

模块尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况)

# 正确的模块名
import decoder
import html_parser

# 不推荐的模块名
import Decoder

7.2、类名

类名使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头。将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块。

class Farm():
    pass

class AnimalFarm(Farm):
    pass

class _PrivateFarm(Farm):
    pass

7.3、函数

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

def run():
    pass

def run_with_env():
    pass

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

class Person():

   	def _private_func():
        pass

7.4、变量名

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

if __name__ == '__main__':
    count = 0
    school_name = ''

7.5、常量名

常量使用以下划线分隔的大写命名。
常量采用全大写，如有多个单词，使用下划线隔开。

MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600