Python开发规范

1、python 开发规范总则概况： python 风格规范，包含了部分google 风格规范和 pep8规范。包括django 项目目录结构的一些规范，为适应我们实际需求，提高开发中代码更加可观性、易读性拟定的规范。第一章命名规范1.1模块模块尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况 ) # 正确的模块名import decoder import html_parser # 不推荐的模块名import decoder 1.2类名1.3函数编写函数的几个原则函数设计要尽量短小，嵌套层次不宜过深；函数申明应做到合理、简单、易于使用，函数名应能正确反映函数大体

2、功能，参数设计应简洁明了，参数个数不宜过多；函数参数设计应考虑向下兼容；一个函数只做一件事，尽量保证函数语句粒度的一致性；1.4变量名避免只用大小写来区分不同的对象；避免使用容易引起混淆的名称，变量名应与所解决的问题域一致；不要害怕过长的变量名；类名使用驼峰(camelcase)命名风格，首字母大写，私有类可用一个下划线开头class farm(): pass class animalfarm(farm): pass class _privatefarm(farm): pass 将相关的类和顶级函数放在同一个模块里. 不像 java, 没必要限制一个类一个模块. 函数名一律小写，如有多个单词，

3、用下划线隔开def run(): pass def run_with_env(): pass 私有函数在函数前加一个下划线_ class person(): def _private_func(): pass 1.5常量1.6其他规则1.所谓”内部 (internal)”表示仅模块内可用 , 或者, 在类内是保护或私有的 . 2.用单下划线 (_)开头表示模块变量或函数是protected 的(使用 import * from时不会包含 ). 3.用双下划线 (_)开头的实例变量或方法表示类内私有. 4.将相关的类和顶级函数放在同一个模块里. 不像 java, 没必要限制一个类一个模块 . 5

4、.对类名使用大写字母开头的单词(如 capwords, 即 pascal风格), 但是模块名应该用小写加下划线的方式(如 lower_with_under.py). 1.7应该避免的名称1.单字符名称2.包/模块名中使用连字符 (-)而不使用下划线 (_) 3.双下划线开头并结尾的名称（如_init_）变量名尽量小写, 如有多个单词，用下划线隔开if _name_ = _main_: count = 0 school_name = 常量采用全大写，如有多个单词，使用下划线隔开max_client = 100 max_connection = 1000 connection_timeout =

5、600 常量使用以下划线分隔的大写命名max_overflow = 100 class foobar: def foo_bar(self, print_): print(print_) 第二章简明概述2.1编码如无特殊情况 , 文件一律使用utf-8 编码如无特殊情况 , 文件头部必须加入 #-coding:utf-8-标识2.2代码格式2.2.1、缩进 统一使用4 个空格进行缩进2.2.2、行宽 每行代码尽量不超过80 个字符 (在特殊情况下可以略微超过80 ，但最长不得超过120) 2.2.3 不要使用反斜杠连接行2.2.4 python 会将 圆括号 , 中括号和花括号中的行隐式的连接起

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

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

8、 x*x + y*y c = (a+b) * (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 ) 字典对象的左括号之

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

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

11、个空格分隔2. 注释由#和一个空格开始，如下：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. 外

12、部不可见2. 非常短小3. 简单明了文档字符串应该包含函数做什么, 以及输入和输出的详细描述文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码 , 只要看文档字符串就可以了对于复杂的代码 , 在代码旁边加注释会比使用文档字符串更有意义. 3.5类类应该在其定义下有一个用于描述该类的文档字符串. 如果你的类有公共属性 (attributes), 那么文档中应该有一个属性(attributes)段. 并且应该遵守和函数参数相同的格式 . 3.6块注释和行注释不推荐的注释3.7 todo 注释1.todo 注释应该在所有开头处包含”todo”字符串 , 紧跟着是用括号括

13、起来的你的名字 , email 地址或其它标识符 . 然后是一个可选的冒号 . 接着必须有一行注释 , 解释要做什么1.1、块注释“ #”号后空一格，段落件用空行分开（同样需要“#”号）# 块注释# 块注释# # 块注释# 块注释1.2、行注释至少使用两个空格和语句分开，注意不要使用无意义的注释# 正确的写法x = x + 1 # 边框加粗一个像素# 不推荐的写法(无意义的注释 ) x = x + 1 # x加 1 1.3、建议在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性app = create_app(nam

14、e, options) # = # 请勿在此处添加get post 等 app 路由行为! # = if _name_ = _main_: app.run() 2.如果你的 todo 是”将来做某事”的形式, 那么请确保你包含了一个指定的日期 (“2009 年 11 月解决” )或者一个特定的事件第四章其他规范4.1 模块导入1. 每个导入应该独占一行2. 模块导入顺序1 标注库导入2 第三方库导入3 应用程序指定导入3. 每种分组中 , 应该根据每个模块的完整包路径按字典序排序, 忽略大小写 . 4.2 二元运算符换行 (pep8) # 推荐：运算符和操作数很容易进行匹配正确的写法impor

15、t os import sys 不推荐的写法import sys,os 正确的写法from subprocess import popen, pipe import 语句应该使用absolute import 正确的写法from foo.bar import bar 不推荐的写法from .bar import bar import 语句应该放在文件头部，置于模块说明及docstring 之后，于全局变量之前；import 语句应该按照顺序排列，每组之间用一个空行分隔import os import sys import msgpack import zmq import foo 导入其他模块

16、的类定义时，可以使用相对导入from myclass import myclass 如果发生命名冲突，则可使用命名空间import bar import foo.bar income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest) 4.3 其它规范1. 不要在行尾加分号 , 也不要用分号将两条命令放在同一行. 2. 除非是用于实现行连接 , 否则不要在返回语句或条件语句中使用括号. 不过在元组两边使用括号是可以的. 3.

17、顶级定义之间空两行 , 方法定义之间空一行4.4pandas 使用规范1. pandas 数据结构命名df_、se_ 2. df 取一列，禁止使用 df. 列名，可以使用 df列名 , 建议使用 df.loc:, 列名3. 禁止使用 df.ix第五章django开发规范django 采用的是 mtv开发模式model(模型)：数据库相关的操作 (orm) template(模版)：模板语法 -将变量（数据库数据）如何巧妙嵌入html 页面中view(视图)：逻辑处理此外， django还有一个 urls 分发器：路径与视图函数的映射关系5.1django目录结构上图 zoneyet=app，w

18、ebdjango 表示 project 每个业务模块可以自建一个model 和与之对应的 view model 目录下主要处理数据model 下每个 model 对应写一个 model 的 manager 业务逻辑方法一般原则上每个 model 对应一个表，对应一个manager 业务处理。view 调用 manager 方法实现，最终通过模板或者接口实现功能。5.2标准化 django模板（ template ）区块 (block) 名称为了尽量标准化django 模板区块(block) 名称, 我建议通常情况下使用以下区块名称 . % block title % 这个区块用来定义页面的标题

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