Code Conventions

General

  1. Programming Practices
    1. Code should be readable and efficient.

    2. Avoid magic numbers (literal primitive numbers) by using variables with meaningful names.

    3. Write functions that are small and do one thing.

    4. Write test cases before writing any code.

    5. Class attributes are for representing an object of a class, not a convenient way to pass information between functions.

  2. Formatting
    1. All lines should be less than 80 characters (the default width of an Emacs window). The best way to ensure that all lines of code are less than 80 characters is to write simple statements that do only one thing. When a line must span multiple lines:

      • break after commas.

      • break before operators.

      • prefer higher level breaks.

    2. Functions should be 40 lines or less, including comments.

    3. Indent with spaces (the default behavior for Emacs), not with tabs.

  3. Documentation
    1. Files should have a block comment at the top with the author and purpose of the file.

    2. All functions should have a block comment above them that includes:

      • A description of the purpose of the function.
      • A description of the data types for all functional parameters. If there are further restrictions on the values of some parameters, they must be stated as well

  4. Declarations
    1. There should be only one variable declaration per line .

    2. Initialize variables on the same line as they are declared, if possible.

    3. Declare variables at the beginning of the block of code in which they will be used.

  5. Statements
    1. Lines should not have more than one statement.

    2. Use only one assignment operator per statement.

    3. Functions should have only one return statement (if any) and it should be the last statement in the function.

  6. White Space
    1. Blank lines should be used to separate related sections of code and should be preceded by a comment explaining the section of code.

    2. Functions should be separated by blank lines.

    3. Binary operators (+, -, *, etc.) should be separated from their operands by spaces (except for the . operator).

    4. Unary operators (-, ++, etc.) should not be separated from their operand by a space.

    5. Argument lists should have spaces after commas.

  7. Naming Conventions
    1. Names for variables, functions, and classes should be meaningful. Common abbreviations are OK (avg, max, etc.) but single character names and acronyms should be avoided.

    2. Function names should start with verbs and describe what the function does.

    3. Class names should be nouns and describe what the class represents.

  8. Python

  9. Programming Practices
    1. Default parameters and named arguments break the spaces around binary operator rule.

    2. Do not use from module_name import *. Instead replace the * with what specifically to import from the module.