python代码规范

为何要有代码规范？

1.作哪一行都有高低级别之分，别写一行代码就被人鄙视了。
2.好的规范会造成好的编码风格，看着熟悉、亲切，心情好。
3.增长可读性，易维护，提升工做效率。
4.遵循规范，代码会本身写代码。
5.国家为啥要有法律，就是为了管理。

 

 

1、简明概述

一、编码

• 如无特殊状况, 文件一概使用 UTF-8 编码

• 如无特殊状况, 文件头部必须加入#-*-coding:utf-8-*-标识

二、代码格式

2.一、缩进

• 统一使用 4 个空格进行缩进

2.二、行宽

每行代码尽可能不超过 80 个字符(在特殊状况下能够略微超过 80 ，但最长不得超过 120)

理由：

• 这在查看 side-by-side 的 diff 时颇有帮助

• 方便在控制台下查看代码

• 太长多是设计有缺陷

2.三、引号

简单说，天然语言使用双引号，机器标示使用单引号，所以 代码里 多数应该使用 单引号

• 天然语言 使用双引号 "..."

例如错误信息；不少状况仍是 unicode，使用u"你好世界"

• 机器标识 使用单引号 '...'

例如 dict 里的 key

• 正则表达式 使用原生的双引号 r"..."

• 文档字符串 (docstring) 使用三个双引号 """......"""

2.四、空行

• 模块级函数和类定义之间空两行；

• 类成员函数之间空一行；

• 可使用多个空行分隔多组相关的函数

• 函数中可使用空行分隔出逻辑相关的代码

2.五、编码

• 文件使用 UTF-8 编码

• 文件头部加入 # -*-conding:utf-8-*- 标识

三、import 语句

• import 语句应该分行书写

• import语句应该使用 absolute import

• import语句应该放在文件头部，置于模块说明及docstring以后，于全局变量以前；

• import语句应该按照顺序排列，每组之间用一个空行分隔

• 导入其余模块的类定义时，可使用相对导入

• 若是发生命名冲突，则可以使用命名空间

四、空格

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

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

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

• 左括号以后，右括号以前不要加多余的空格

• 字典对象的左括号以前不要多余的空格

• 不要为对齐赋值语句而使用的额外空格

五、换行

Python 支持括号内的换行。这时有两种状况。

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

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

使用反斜杠换行，二元运算符+ .等应出如今行末；长字符串也能够用此法换行

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

if/for/while必定要换行：

六、docstring

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

1. 全部的公共模块、函数、类、方法，都应该写 docstring 。私有方法不必定须要，但应该在 def 后提供一个块注释来讲明。

2. docstring 的结束”“”应该独占一行，除非此 docstring 只有一行。

 

2、注释

一、注释

1.一、块注释

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

1.二、行注释

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

1.三、建议

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

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

二、文档注释（Docstring）

做为文档的Docstring通常出如今模块头部、函数和类的头部，这样在python中能够经过对象的__doc__对象获取文档.

编辑器和IDE也能够根据Docstring给出自动提示.

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

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

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

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

• 文档注释不是越长越好, 一般一两句话能把状况说清楚便可

• 模块、公有类、公有方法, 能写文档注释的, 应该尽可能写文档注释

 

3、命名规范

一、模块

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

二、类名

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

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

三、函数

四、变量名

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

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

五、常量

常量使用如下划线分隔的大写命名

 

 

四. 主要命名规范
模块名采用小写字母而且如下划线分隔单词的形式；

包名应当简短，使用全小写，可是不要使用下划线

类名采用以大写字母开头，而且以大写字母分隔单词的形式命名（驼峰式命名）；

全局或者类常量，所有使用大写字母，而且如下划线分隔单词；其他变量命名则是采用所有小写字母，而且如下划线分隔单词的形式命名。

以上的内容若是是内部的，则使用下划线开头命名。

类型

公共（全局）

内部

模块名

lower_with_under

_ lower_with_under

包名

lowerwithoutunder

 

类名

CapWords

_ CapWords

异常名

CapWords

 

函数名

lower_with_under( )

_ lower_with_under( )

全局/类常量

CAPS_WITH_UNDER

_ CAPS_WITH_UNDER

全局/类变量

lower_with_under

_ lower_with_under

实例变量

lower_with_under

_ lower_with_under（单下划线私有）

__lower_with_under（双下划线避免与子类冲突）

方法名

lower_with_under( )

_ lower_with_under()（单下划线私有）

__lower_with_under()（双下划线避免与子类命名冲突）

函数/方法参数

lower_with_under

 

本地变量

lower_with_under

 

注：

一、from M import * 不会导入如下划线开始的对象。

二、异常也是一个类，因此须要遵循类名规则。但若是你的异常确实是个错误的话，请使用Error前缀

三、函数与方法参数设置时，使用self做为实例方法的第一个参数。使用cls做为类方法的第一个参数。当函数的参数名与保留字冲突时，使用下划线后缀（第二次提醒）。

四、方法名与实例变量设置时，在私有方法和实例变量前用单下划线前缀。使用双下划线前缀来调用"name mangling"来避免与子类命名冲突。若是类Foo有个属性叫__a，那么它不能使用Foo.__a读取，但仍然能够Foo._Foo__a来读取

五、应避免使用的命名：不要使用小写的L、大写的O、以及大写的I做为单字符变量名。__double_leading_and_trailing_underscore__：（双下划线开始和结束）存活在用户控制命名空间的"magic"对象或属性。例如__init__, __import__ 或 __file__。永远不要起这样的名字。