Python开发规范

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

2、rm(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 = '' 常量采用全大写，如有多个单词，使用下划线隔开 M

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

5、的方式(如lower_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.4 Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你

6、可以利用这个特点. 如果需要, 你可以在表达式外围增加一对额外的圆括号.对于行连接的情况, 你应该要么垂直对齐换行的元素, 或者使用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 )字典对象的左括号之前不要多余的空格正确的写法dict'k

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

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

11、释由#和一个空格开始，如下：x = x + 1 # Compensate 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. 非常短小

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

13、无意义的注释# 正确的写法x = x + 1 # 边框加粗一个像素3.6块注释和行注释不推荐的注释# 不推荐的写法(无意义的注释)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”字符串, 紧跟着是用括号

14、括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么 2.如果你的TODO是”将来做某事”的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件第四章 其他规范4.1模块导入1. 每个导入应该独占一行2. 模块导入顺序1标注库导入2第三方库导入3应用程序指定导入正确的写法import osimport sys不推荐的写法import sys,os正确的写法from subprocess import Popen, PIPEimport语句应该使用 absolute import 正确的写法from foo

15、.bar import Bar不推荐的写法from .bar import Barimport语句应该放在文件头部，置于模块说明及docstring之后，于全局变量之前；import语句应该按照顺序排列，每组之间用一个空行分隔import osimport sysimport msgpackimport zmqimport foo导入其他模块的类定义时，可以使用相对导入from myclass import MyClass3. 每种分组中, 应该根据每个模块的完整包路径按字典序排序, 忽略大小写.如果发生命名冲突，则可使用命名空间import barimport foo.bar4.2二元运算符

16、换行(PEP8)# 推荐：运算符和操作数很容易进行匹配income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)4.3其它规范1.不要在行尾加分号, 也不要用分号将两条命令放在同一行. 2.除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号. 不过在元组两边使用括号是可以的. 3.顶级定义之间空两行, 方法定义之间空一行4.4Pandas使用规范1. pandas数据结构命名 df_、se_2. df取一列，

17、禁止使用df.列名，可以使用df'列名', 建议使用df.loc:, '列名'3. 禁止使用df.ix第五章 Django开发规范Django 采用的是MTV开发模式Model(模型)：数据库相关的操作(ORM)Template(模版)：模板语法->将变量（数据库数据）如何巧妙嵌入html页面中View(视图)：逻辑处理此外，Django还有一个urls分发器：路径与视图函数的映射关系5.1Django目录结构上图zoneyet=app，webDjango表示project每个业务模块可以自建一个model和与之对应的viewmodel目录下主要处理数据m

18、odel下每个model对应写一个model的Manager业务逻辑方法一般原则上每个model对应一个表，对应一个Manager业务处理。view调用Manager方法实现，最终通过模板或者接口实现功能。5.2标准化Django模板（Template）区块 (block) 名称为了尽量标准化 Django 模板区块 (block) 名称, 我建议通常情况下使用以下区块名称.% block title %这个区块用来定义页面的标题. 你的 base.html 模板很可能要在这个 tag 之外定义 站点名字 (Site's name) (即便使用了 Sites 框架), 以便能够放在所有

19、页面中.% block extra_head %我认为这是个非常有用的区块, 很多人已经以某种方式在使用了. 很多页面经常需要在 HTML 文档头添加些信息, 比如 RSS 源, Javascript, CSS, 以及别的应该放在文档头的信息. 你可以, 也很可能将会, 定义另外专门的区块 (比如前面的 title 区块) 来添加文档头的其它部分的信息.% block body %这个 tag 用来包含页面的整个 body 部分. 这使得你在 app 中创建的页面 能够替换整个页面内容, 不仅仅是正文内容. 这种做法虽不常见, 但当你需要时, 它确实是一个非常方便的 tag. 你可能还没注意到, 我一直尽可能的使 tag 名字和 HTML 标签名称保持一致.% block menu %你的菜单 (导航栏) 应该包含在