Project

General

Profile

Style guide

For code

This section is specifically for code.

Formatting

  • Files should be encoded with UTF-8.
  • Always use Unix-style (LF, not CRLF) line endings. If you are on Windows, use an editor that supports Unix-style line endings (e.g., Sublime Text), or modify your Git settings to set line endings to Unix-style.

Syntax and punctuation

  • When making a new file, use 4 spaces for indentation instead of tabs. When working on an existing file, use whatever that file is already using.
  • Use double quotes for single-line strings.
  • If the contents of a pair of brackets or parentheses span multiple lines, then the following rules should generally be observed:

    1. The opening bracket/parenthesis should be the last character of its line (excluding comments).
    2. The contents should be one indentation level deeper than the opening bracket/parenthesis.
    3. The closing bracket/parenthesis should be on its own line, at the same indentation level as the opening bracket/parenthesis.

    Here's an example in Lua:

    local mylist = {
        "orange",
        "strawberry",
        "banana"
    }
    

    Sometimes there are exceptions to the first and third rules, such as in Lua class definitions:

    local MyClass = class.define(function(self, x)
        self.x = x
    end)
    
  • Try not to have lines of code exceed 100 characters each. Limit lines of comments to 79 characters each.

Spelling

  • Use American English for all names and strings.
  • Use CamelCase for all names. The first letter should be upper case for names of classes. For anything else, the first letter should be lower case.
  • "Private" variable names should begin with a single underscore.

Python-specific

  • Unless the project requirements state otherwise, all Python code should be compatible with the latest versions of Python 2 and Python 3. (We often use the Six library to facilitate this.)
  • Python imports should be grouped this way, in the following order:

    • __future__
    • built-in modules
    • names from built-in modules
    • external modules
    • names from external modules
    • modules from this package
    • names from modules from this package

    Here is an example:

    from __future__ import unicode_literals
    import sys, os # built-in modules
    import yaml # external module
    from six import text_type, binary_type # names from external module
    from . import models # modules from this package
    

    Imports should be explicitly relative or absolute.

For words

This section is specifically for prose (e.g., wiki edits, documentation). It does not apply to comments or forum posts.

  • In contrast to our policy for code, we prefer to use Canadian English for general wriitng.
  • Make sure not to mix up hyphens, en dashes, and em dashes.
  • Capitalize only the first word of wiki and issue titles.