Coding style for existing products

When writing code for existing products, most of them will have a coding style explicitly written or implicitly implied. An example of the former is Moodle's coding style, a clearly documented style for developers working to extend Moodle.

Coding style for new projects

For new projects being written from the ground up, we will follow Guido van Rossum's guidelines. Style guidelines exist for both Python (which can be applied to Python-esque languages) and C (also applicable to similar languages).

Summary of Python style

• Indentation: Use 4 spaces per indentation level.
• Tabs or spaces: Never mix, spaces preferred.
• Maximum line length: 79
• Blank lines: Separate top-level function and class definitions with 2 blank lines, method definitions inside a class are separated by 1 blank line, extra blank lines may be used to separate groups of related functions, and omitted between related one-liners. Blank lines may be used in functions to indicate sections.
• Encodings: ASCII, or UTF-8 for Python 3.0.
• Imports:
  • Imports should be on separate lines, except for multiple imports from one source.
  • Imports should always be at the top of a file, immediately after comments and before globals.
  • Imports should be in the order of standard library imports, related third party imports, and then local application imports.
  • Use absolute package path for imports, not relative imports.
• Whitespace:
  • Avoid extraneous whitespace:
    • Immediately inside parens, brackets, or braces.
    • Immediately before a comma, semicolon, or colon.
    • Immediately before the open parens that contains arguments for a function call.
    • To pad out assignments to line them up.
  • Surround assignment, augmented assignment, comparisons, booleans, and arithmetic operators with a single space on either side.
    • However, do not use spaces around assignment when indicating a keyword argument or default value.
• Compound statements on one line are discouraged, particularly for multi-clause statements.
• Comments need to be kept up to date, complete sentences with proper capitalization, though if a single line the period can be omitted. Two spaces should follow each sentence-ending period. Block comments usually apply to the code that follows them. Inline comments (on the same line as code) should be used sparingly, and never just state the obvious.
• Write documentation strings for all public modules, functions, classes, and methods. They are not necessary for non-public methods, but they should still be commented.
  • SVN notation should follow the documentation string.
• Naming:
  • Modules, global variables, method names, instance variables, and functions should have short all-lowercase names, with an underscore if it improves readability.
  • Class names should have the first letter of each word capitalized. Exceptions follow this convention, ending with Error if the exception is an error.
  • Constants should be entirely capitalized.
• When deciding if a class's methods and instance variables should be public or non-public, err on the side of the latter.
• Be careful with singletons like None. Use is or is not, not the equality comparison. And be wary of saying "if x" when meaning "if x is not None". But do not use the equality comparison to compare boolean values, and use the fact that empty sequences are false with such assertions.

Summary of C style

• Use ANSI/ISO standard C (all declarations must be at the top of a block).
• Don't use GCC extensions.
• Specify the types of all arguments.
• Never use C++ style // one-line comments.
• Do not allow any compiler warnings with major compilers (gcc, VC++, etc).
• Use single-tab intents when already using tabs, otherwise and in completely new files use 4 space indents.
• Line length of 79, not ending in any whitespace.
• Functions should be defined with the name in column 1, the outermost curly brace in column 1, and a blank line after local variable definitions.
• One space between keywords such as if or for and the following left paren. No spaces inside the paren.
• Avoid redundant parens.
• Functions and macro calls should be in the style of foo(a, b, c).
• Always put spaces around assignment, Boolean, and comparison operators. When using a large number of operators, add spaces around the outermost operators.
• When breaking long lines, attempt to do so after a comma, and indent continuation lines appropriately.
  • When breaking a long line at a binary operator, the operator ends the line instead of starting the new line.
• Put blank lines around functions, structure definitions, and major sections inside functions.
• Comments before the code they describe.
• All functions and global variables should be static unless they are designed to be part of a published interface.
• Public functions and variables use mixed case with underscores.
• Macros should have a mixed case prefix and then be entirely capitalized.
• The first line of each function's documentation string should be a signature line that summarizes the inputs and output.