General coding guidelines¶

Language¶

British English is preferred for user-facing text; this text should also be marked for translation (using the django.utils.translation.gettext function and {% translate %} template tag, for example). However, identifiers within code should use American English if the British or international spelling would conflict with built-in language keywords; for example, CSS code should consistently use the spelling color to avoid inconsistencies like background-color: $colour-red.

Latin phrases and abbreviations¶

Try to avoid Latin phrases (such as ergo or de facto) and abbreviations (such as i.e. or e.g.), and use common English phrases instead. Alternatively, find a simpler way to communicate the concept or idea to the reader. The exception is etc. which can be used when space is limited.

Examples:

Don’t use this	Use this instead
e.g.	for example, such as
i.e.	that is
viz.	namely
ergo	therefore

File names¶

Where practical, try to adhere to the existing convention of file names within the folder where added.

Examples:

Django templates - lower_snake_case.html
Documentation - lower_snake_case.md

Naming conventions¶

Use `classname` in Python / HTML template tag variables¶

classname is preferred for any API / interface or Django template variables that need to output an HTML class.

Django template tag¶

Example template tag definition

@register.inclusion_tag("wagtailadmin/shared/dialog/dialog_toggle.html")
def dialog_toggle(dialog_id, classname="", text=None):
    return {
        "classname": classname,
        "text": text,
    }

Example template

{% comment "text/markdown" %}

    Variables accepted by this template:

    - `classname` - {string?} if present, adds classname to button
    - `dialog_id` - {string} unique id to use to reference the modal which will be triggered

{% endcomment %}

<button type="button" class="{{ classname }}" data-a11y-dialog-show="{{ dialog_id }}">
    {{ text }}
</button>

Example usage

{% dialog_toggle classname='button button-primary' %}

Python / Django class driven content¶

class Panel:
    def __init__(self, heading="", classname="", help_text="", base_form_class=None):
        self.heading = heading
        self.classname = classname

Details¶

Convention	Usage
`classname`	✅ Preferred for any new code.
`class`	✳️ Only if used as part of a generic `attrs`-like dict; however avoid due to conflicts with Python `class` keyword.
`classnames`	❌ Avoid for new code.
`class_name`	❌ Avoid for new code.
`class_names`	❌ Avoid for new code.
`className`	❌ Avoid for new code.
`classNames`	❌ Avoid for new code.