django开发规范

文章目录[隐藏]

1. python风格
2. python文件要求
3. 文件头
4. 包引入
5. 注释
6. model规范
7. 目录优化

本文只约定在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就可以直接引用了。

本网站采用知识共享署名-相同方式共享 4.0 国际许可协议进行授权
转载请注明原文链接：django开发规范