记录学习笔记、分享资源工具、交流技术思想、提升工作效率

django开发规范

后端 xiaomudk 2年前 (2019-03-01) 1122次浏览 0个评论
文章目录[隐藏]

本文只约定在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开发规范
发表我的评论
取消评论

表情 贴图 加粗 删除线 居中 斜体 签到

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址