Python开发规范.docx

1、Python开发规范 Python开发规范总则概况：Python风格规范 ，包含了部分Google风格规范和PEP8规范。包括Django项目目录结构的一些规范，为适应我们实际需求，提高开发中代码更加可观性、易读性拟定的规范。第一章命名规范1.1模块模块尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况)# 正确的模块名 import decoder import html_parser # 不推荐的模块名 import Decoder类名使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头 class Farm(): pass clas

2、s AnimalFarm(Farm): pass class _PrivateFarm(Farm): pass 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.1.2类名函数名一律小写，如有多个单词，用下划线隔开 def run(): pass def run_with_env(): pass 私有函数在函数前加一个下划线_ class Person(): def _private_func(): pass1.3函数编写函数的几个原则函数设计要尽量短小，嵌套层次不宜过深；函数申明应做到合理、简单、易于使用，函数名应能正确反映函数大体功能，参数设计应简洁明了，参

3、数个数不宜过多；函数参数设计应考虑向下兼容；一个函数只做一件事，尽量保证函数语句粒度的一致性；1.4变量名避免只用大小写来区分不同的对象；避免使用容易引起混淆的名称，变量名应与所解决的问题域一致；不要害怕过长的变量名；常量使用以下划线分隔的大写命名 MAX_OVERFLOW = 100 Class FooBar: def foo_bar(self, print_): print(print_)变量名尽量小写, 如有多个单词，用下划线隔开 if _name_ = _main_: count = 0 school_name = 常量采用全大写，如有多个单词，使用下划线隔开 MAX_CLIENT =

4、 100 MAX_CONNECTION = 1000 CONNECTION_TIMEOUT = 6001.5常量1.6其他规则1.所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的. 2.用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含). 3.用双下划线(_)开头的实例变量或方法表示类内私有. 4.将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块. 5.对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_

5、with_under.py).1.7应该避免的名称1.单字符名称2.包/模块名中使用连字符(-)而不使用下划线(_)3.双下划线开头并结尾的名称（如_init_）第二章 简明概述2.1编码如无特殊情况, 文件一律使用 UTF-8 编码 如无特殊情况, 文件头部必须加入#-coding:utf-8-标识2.2代码格式2.2.1、缩进 统一使用 4 个空格进行缩进 2.2.2、行宽 每行代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ，但最长不得超过 120) 2.2.3不要使用反斜杠连接行2.2.4Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这个特

6、点. 如果需要, 你可以在表达式外围增加一对额外的圆括号.2.2.5对于行连接的情况, 你应该要么垂直对齐换行的元素, 或者使用4空格的悬挂式缩进(这时第一行不应该有参数):理由： 这在查看 side-by-side 的 diff 时很有帮助 方便在控制台下查看代码 太长可能是设计有缺陷2.3引号简单说，自然语言使用双引号，机器标示使用单引号，因此 代码里 多数应该使用 单引号 自然语言 使用双引号 “” 例如错误信息；很多情况还是 unicode，使用u”你好世界” 机器标识 使用单引号 例如 dict 里的 key 正则表达式 使用原生的双引号 r” 文档字符串 (docstring) 使

7、用三个双引号 “”“”“”2.4空行模块级函数和类定义之间空两行； class A: def _init_(self): pass def hello(self): pass def main(): pass 可以使用多个空行分隔多组相关的函数函数中可以使用空行分隔出逻辑相关的代码类成员函数之间空一行；正确的写法i = i + 1submitted += 1x = x * 2 - 1hypot2 = x * x + y * yc = (a + b) * (a - b)不推荐的写法i=i+1submitted +=1x = x*2 - 1hypot2 = x*x + y*yc = (a+b) *

8、 (a-b)函数的参数列表中，,之后要有空格正确的写法def complex(real, imag): pass 不推荐的写法def complex(real,imag): pass函数的参数列表中，默认值等号两边不要添加空格 正确的写法def complex(real, imag=0.0): pass 不推荐的写法def complex(real, imag = 0.0): pass左括号之后，右括号之前不要加多余的空格 正确的写法spam(ham1, eggs: 2)不推荐的写法spam( ham1, eggs : 2 )字典对象的左括号之前不要多余的空格正确的写法dictkey = li

9、stindex不推荐的写法dict key = list index不要为对齐赋值语句而使用的额外空格正确的写法x = 1y = 2long_variable = 3 不推荐的写法x = 1y = 2long_variable = 32.5空格1.括号内不要有空格2.不要在逗号，分号，冒号前面加空格，而应该在它们的后面加3.二元操作符两边都要加上一个空格（=， =，, !=, in, not .）4.当=用于指示关键字参数或默认参数值时5.不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于:, #, =等)2.6换行第三章 注释规范3.1文档字符串Python使用文档字符串作为

10、注释方式: 文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的doc成员被自动提取, 并且被pydoc所用. 我们对文档字符串的惯例是使用三重双引号”“”( PEP-257 ). 一个文档字符串应该这样组织: 1. 首先是一行以句号, 问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行. 2. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐.3.2行内注释(PEP8)行内注释是与代码语句同行的注释 1. 行内注释和代码至少要有两个空格分隔 2. 注释由#和一个空格开始，如下：x = x + 1 # Compensate

11、for border3.3模块注释每个文件应该最好包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.# -*- coding: utf-8 -*-# (C) Zoneyet, Inc. 2018-2019# All rights reserved# Licensed under Simplified BSD License (see LICENSE)3.4函数和方法一个函数必须要有文档字符串, 除非它满足以下条件: 1. 外部不可见 2. 非常短小 3. 简单明了文档字符串应该包含函数做什么, 以及输入和输出的详细描述 文

12、档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了 对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.3.5类类应该在其定义下有一个用于描述该类的文档字符串. 如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.1.1、块注释“#”号后空一格，段落件用空行分开（同样需要“#”号）# 块注释# 块注释# 块注释# 块注释1.2、行注释至少使用两个空格和语句分开，注意不要使用无意义的注释# 正确的写法x = x + 1 # 边框加粗一个像素3.6块

13、注释和行注释不推荐的注释# 不推荐的写法(无意义的注释)x = x + 1 # x加11.3、建议在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性app = create_app(name, options)# =# 请勿在此处添加 get post等app路由行为 !# =if _name_ = _main_: app.run()3.7 TODO注释1.TODO注释应该在所有开头处包含”TODO”字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释,

14、 解释要做什么 2.如果你的TODO是”将来做某事”的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件第四章 其他规范4.1模块导入1.每个导入应该独占一行2.模块导入顺序1标注库导入2第三方库导入3应用程序指定导入3.正确的写法import osimport sys不推荐的写法import sys,os正确的写法from subprocess import Popen, PIPEimport语句应该使用 absolute import 正确的写法from foo.bar import Bar不推荐的写法from .bar import Barimport语句应该放在文件头部，置于模块说明及docstring之后，于全局变量之前；import语句应该按照顺序排列，每组之间用一个空行分隔import osimport sysimport msgpackimport zmqimport foo导入其他模块的类定义时，可以使用相对导入from myclass import MyClass每种分