diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index ef5685bea9..7f825da90a 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -214,20 +214,149 @@ Imports Template style ============== -* In Django template code, put one (and only one) space between the curly - brackets and the tag contents. +Follow the below rules in Django template code. + +* ``{% extends %}`` should be the first non-comment line. Do this: .. code-block:: html+django - {{ foo }} + {% extends "base.html" %} + + {% block content %} +

+ {{ pages.title }} +

+ {% endblock content %} + + Or this: + + .. code-block:: html+django + + {# This is a comment #} + {% extends "base.html" %} + + {% block content %} +

+ {{ pages.title }} +

+ {% endblock content %} Don't do this: .. code-block:: html+django - {{foo}} + {% load i18n %} + {% extends "base.html" %} + + {% block content %} +

+ {{ pages.title }} +

+ {% endblock content %} + +* Put exactly one space between ``{{``, variable contents, and ``}}``. + + Do this: + + .. code-block:: html+django + + {{ user }} + + Don't do this: + + .. code-block:: html+django + + {{user}} + +* In ``{% load ... %}``, list libraries in alphabetical order. + + Do this: + + .. code-block:: html+django + + {% load i18n l10 tz %} + + Don't do this: + + .. code-block:: html+django + + {% load l10 i18n tz %} + +* Put exactly one space between ``{%``, tag contents, and ``%}``. + + Do this: + + .. code-block:: html+django + + {% load humanize %} + + Don't do this: + + .. code-block:: html+django + + {%load humanize%} + +* Put the ``{% block %}`` tag name in the ``{% endblock %}`` tag if it is not + on the same line. + + Do this: + + .. code-block:: html+django + + {% block header %} + + Code goes here + + {% endblock header %} + + Don't do this: + + .. code-block:: html+django + + {% block header %} + + Code goes here + + {% endblock %} + +* Inside curly braces, separate tokens by single spaces, except for around the + ``.`` for attribute access and the ``|`` for a filter. + + Do this: + + .. code-block:: html+django + + {% if user.name|lower == "admin" %} + + Don't do this: + + .. code-block:: html+django + + {% if user . name | lower == "admin" %} + + {{ user.name | upper }} + +* Within a template using ``{% extends %}``, avoid indenting top-level + ``{% block %}`` tags. + + Do this: + + .. code-block:: html+django + + {% extends "base.html" %} + + {% block content %} + + Don't do this: + + .. code-block:: html+django + + {% extends "base.html" %} + + {% block content %} + ... View style ==========