Coding style

编写代码以包含在Django中时,请遵循这些编码标准。

Python style

  • 除非另有规定,请遵循 PEP 8

    使用flake8检查此区域中的问题。请注意,我们的setup.cfg文件包含一些排除的文件(不推荐使用的模块,我们不关心清理和一些第三方代码Django供应商)以及一些排除的错误,我们不认为是严重违反。请记住, PEP 8只是一个指南,因此请将周围代码的风格作为主要目标。

    PEP 8的例外是我们对线长度的规则。如果代码看起来明显更丑陋或更难阅读,请不要将代码行限制为79个字符。我们允许最多119个字符,因为这是GitHub代码审查的宽度;任何更长的需要水平滚动,这使得审查更加困难。当您运行flake8时,会包含此检查。即使 PEP 8建议72,文档,注释和文档字符串应包含79个字符。

  • 使用四个空格缩进。

  • 对变量,函数和方法名称使用下划线,而不是camelCase。poll.get_unique_voters(),而不是poll.getUniqueVoters)。

  • 对类名(或返回类的工厂函数)使用InitialCaps

  • 每当可用时使用便利导入。例如,执行以下操作:

    from django.views.generic import View
    

    不要这样:

    from django.views.generic.base import View
    
  • 在docstrings中,使用“动词”,如:

    def foo():
        """
        Calculates something and returns the result.
        """
        pass
    

    这里有一个例子,说明不要做什么:

    def foo():
        """
        Calculate something and return the result.
        """
        pass
    

Template style

  • 在Django模板代码中,在大括号和标记内容之间放置一个(且只有一个)空格。

    做这个:

    {{ foo }}
    

    不要这样:

    {{foo}}
    

View style

  • 在Django视图中,视图函数中的第一个参数应该是request

    做这个:

    def my_view(request, foo):
        # ...
    

    不要这样:

    def my_view(req, foo):
        # ...
    

Model style

  • 字段名称应该全部为小写,使用下划线而不是camelCase。

    做这个:

    class Person(models.Model):
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
    

    不要这样做:

    class Person(models.Model):
        FirstName = models.CharField(max_length=20)
        Last_Name = models.CharField(max_length=40)
    
  • 在定义字段之后, Meta应出现在之后,用一个空白行分隔字段和类定义。

    做这个:

    class Person(models.Model):
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
    
        class Meta:
            verbose_name_plural = 'people'
    

    不要这样:

    class Person(models.Model):
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
        class Meta:
            verbose_name_plural = 'people'
    

    不要这样做,要么:

    class Person(models.Model):
        class Meta:
            verbose_name_plural = 'people'
    
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
    
  • 如果你定义一个__str__方法(以前__unicode__,在支持Python 3之前),请使用python_2_unicode_compatible()装饰模型类。

  • 模型内部类和标准方法的顺序应该如下(注意,这些并不都是必需的):

    • 所有数据库字段
    • 自定义管理器属性
    • class Meta
    • def __ str __()
    • def save()
    • def get_absolute_url()
    • 任何自定义方法
  • 如果为给定模型字段定义了choices,请将每个选项定义为元组的元组,其中全大写名称作为模型上的类属性。例:

    class MyModel(models.Model):
        DIRECTION_UP = 'U'
        DIRECTION_DOWN = 'D'
        DIRECTION_CHOICES = (
            (DIRECTION_UP, 'Up'),
            (DIRECTION_DOWN, 'Down'),
        )
    

Use of django.conf.settings

模块通常不应使用存储在顶层(django.conf.settings)中的设置。评估模块导入时)。解释如下:

手动配置设置(即不依赖于DJANGO_SETTINGS_MODULE环境变量)是允许的,可能如下:

from django.conf import settings

settings.configure({}, SOME_SETTING='foo')

但是,如果在settings.configure行之前访问任何设置,这将不起作用。(在内部,settingsLazyObject,如果尚未配置,则在访问设置时自动配置本身)。

所以,如果有一个模块包含一些代码如下:

from django.conf import settings
from django.core.urlresolvers import get_callable

default_foo_view = get_callable(settings.FOO_VIEW)

...然后导入此模块将导致设置对象被配置。这意味着第三方在顶层导入模块的能力与手动配置设置对象的能力不一致,或者在某些情况下非常困难。

代替上述代码,必须使用惰性或间接级别,例如django.utils.functional.LazyObjectdjango.utils.functional.lazy()lambda

Miscellaneous

  • 标记所有字符串以进行国际化;有关详细信息,请参阅i18n documentation
  • 删除更改代码时不再使用的import语句。flake8会为您识别这些导入。如果未使用的导入需要保留以实现向后兼容性,请标记 NOQA的结尾,以停止flake8警告。
  • 系统地从代码中删除所有结尾的空格,因为这些添加了不必要的字节,给补丁添加了视觉混乱,并且偶尔也会导致不必要的合并冲突。一些IDE可以配置为自动删除它们,并且大多数VCS工具可以设置为在差异输出中突出显示它们。
  • 请不要把你的名字放在你贡献的代码。我们的政策是将贡献者的名称保存在与Django一起分发的AUTHORS文件中 - 不分散在整个代码库中。如果您做出一个以上的细微更改,请随意在修补程序中包含对AUTHORS文件的更改。