本文只约定在django项目开发中的规范。如果其它python项目,可以参考此规范。
统一的编码风格,良好的设计理念,有利于项目的开发和维护,值得开发人员不断地研究和探讨
1. python风格
- 除非特殊声明, 否则请遵循 PEP 8 风格指南。
- PEP 8 规定代码行长最长不能超过 79 个字符,但是现在的高分辨率的显示器可以显示超过 79 个字符的代码行。所以代码行最大长度改为119个字符。
- 使用四个空格进行缩进。
- 对字符串使用单引号,如果字符串包含单引号,则使用双引号。不要浪费时间对现有代码进行无关的重构以符合这种风格。
- 使用下划线而不是小驼峰法(camelCase)命名变量、函数及方法名(比如,poll.get_unique_voters(),不要使用 poll.getUniqueVoters)。
- 使用首字母大写(InitialCaps)的方式命名类名(或能够返回类的工厂函数)。
- 支持部分不遵守pep8规范,但是必须为
# NOQA
来标识。
示例:from .model import * #NOQA
2. python文件要求
- 文件编码统一使用utf-8, 换行符为
\n
3. 文件头
- 文件头部不必包含utf-8编码声明和Shebang(#!开头的统称为Shebang)
-
头部可以使用标准的文档字符串标识该文件的作用
""" package.module ~~~~~~~~~~~~~~ A brief description goes here. :copyright: (c) YEAR by AUTHOR. :license: LICENSE_NAME, see LICENSE_FILE for more details. """
4. 包引入
-
使用
isort
可以使用以下指南自动执行导入排序。$ python -m pip install isort $ isort -rc .
isort从当前目录递归运行,修改任何不符合指南的文件。如果您需要无序导入(例如,为了避免循环导入),请使用如下注释:
import module # isort:skip
-
导入顺序分组: future,标准库,第三方库,其他Django组件,本地Django组件,try / excepts。
-
在每个分组中按完整模块名称的字母顺序进行排序。
-
import module
语句要放在from module import objects
之前。 -
Django组件使用绝对导入,对本地组件使用相对导入。
-
太长的import, 使用括号换行,并且使用四个空格缩进.在最后一个import后面加上逗号,并且闭合的括号放在列头。
-
最后一个import后空一行。如果其后是函数或类,空两行
示例:
# future
from __future__ import unicode_literals
# standard library
import json
from itertools import chain
# third-party
import bcrypt
# Django
from django.http import Http404
from django.http.response import (
Http404, HttpResponse, HttpResponseNotAllowed, StreamingHttpResponse,
cookie,
)
# local Django
from .models import LogEntry
# try/except
try:
import yaml
except ImportError:
yaml = None
CONSTANT = 'foo'
class Example:
# ...
5. 注释
- 用
#
表示当前实现以及这种实现的原理和难点 - 如果
#
有代码,必须空两格以上 - 所有的公共模块、函数、类、方法,都应该写docstring(以三个双引号开始,三个双引号结尾)
- docstring的结束"""应该独占一行,除非此docstring只有一行。
- docstring文档遵守reST风格,必须包含:功能注释,参数介绍,返回值格式
docstring示例
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
6. model规范
- 字段名称应当全部使用小写,使用下划线替代驼峰命名。
- 字段必须使用
verbose_name
加上注释。 - class Meta 类应该位于定义字段之后,用一个空行分割字段定义和类定义。
-
模型内方法的定义应该遵循以下顺序(不是所有项都是必须的):
所有数据库字段 自定义管理器属性 class Meta def __str__() def save() def get_absolute_url() 其他自定义方法
- 定义
choices
字段,必须在Model头部定义好list或者tuples, 名称必须全部大写
示例:class MyModel(models.Model): DIRECTION_UP = 'U' DIRECTION_DOWN = 'D' DIRECTION_CHOICES = [ (DIRECTION_UP, 'Up'), (DIRECTION_DOWN, 'Down'), ]
7. 目录优化
- 当一个python文件过大时,可以在一个包内分割为多个文件。package通过一个目录来实现,它包含多个文件,所有在包级别中暴露的定义都必须在init.py里使用全局变量域定义。
例如,分割model.py到独立的类,models子文件夹中的对应文件,比如,postable.py,post.py和comment.py, 之后__init__.py包会像这样: from postable import Postable from post import Post from commnet import Comment
使用models.Post就可以直接引用了。