Code Conventions

General

  1. Programming Practices

    1. Code should be readable and efficient.

    2. Avoid magic numbers (literal primitive numbers) and magic strings 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
      • The pre and post conditions of the function. If the pre conditions are met before execution, then the post conditions are guaranteed to be true on completion. The precondition must document every parameter and any instance variables used in the function. The postcondition should document all variables that may change during execution and the return value.

  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. c. Do not use the assignment operator in conditional and loop statements except when required (i.e. a for loop).

    4. 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.