WARNING: This document is a live and should be followed, code reviews can/should be sent back for correction.

The LAVA team tries to adhere to one coding style standard. This is especially important with a distributed team touching on a number (10+) projects in several different programming languages (Python, PHP, Java, shell).

In short, we follow PEP-8 for Python, PEAR style for PHP, and similar styles for the rest.

Summary of the style

  • 79-character line limit
  • Indentation of 4 whitespaces
  • ClassNames, function_names, method_names, (methodNames for Java), file_names (file-names allowed too where applicable, e.g. for Python non-modules, shell, etc.)

  • Comments should be full sentences ending with punctuation, and always on separate lines from code.
  • C-like languages: curly brackets, comments:

   /**
    * Do smart stuff.
    *
    * Elaborate description if needed, perhaps some *doc syntax.
    */
   int foo() {
       // Start stupid.
       blah();
       ...
   }

Noted extensions

  • Everything should be tested. Both unit and integration tested.
  • Tests should generally live in tests/ subdirectory of a module they are affecting. It's fine to have more than one tests/ subdirectory in a single project if that helps with code organisation.
  • Test filenames should generally be test_module.* (which contains tests for module.*).
  • ..

Exceptions

Borrowed from the PEP-8 standard. Two good reasons to break a particular rule:

  1. When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.
  2. To be consistent with surrounding code that also breaks it (maybe for historic reasons) -- although this is also an opportunity to clean up someone else's mess (in true XP style).

Of course if you break the style, it is perfectly acceptable to be asked to fix your code to comply with the style during a code review. In this case if you can't come up with code that matches the style and is also readable, asking the reviewer to show how they would lay out the code is a great way of learning and, of course, if no "fixed" layout works, that answers that part of the review nicely!

Platform/LAVA/CodingStyle (last modified 2013-07-29 22:06:35)