wiki:CodingStandards

Based on...

As discussed by the devleopment team. These standards will evolve as the project develops.

Code Layout

  • Identation is 4 spaces per level. No tabs.
  • Maximum line length is 79 characters (except where JavaScript makes this impossible).
  • Do not nest control structures more than 4 levels deep, break out into subfunctions
  • Separate functions, classes, and logic with blank lines
  • Each statement should be on a separate line, e.g. 
            if input == 'blah':
            doSomething()
  • Functions should not be longer than 2 pages (120 lines), refactor into subfunctions
  • Use only lowercase in filenames (saves clashes when transfering files to Windows/DOS)

Spaces

  • Spaces go before and after = == < > >= <= != !
    • (except around '=' in default arguments to functions)
  • Spaces go after : ,
  • Parentheses (), and square-brackets [] have no spaces
  • arithmetic and string operators may be used without spaces, e.g. 
            x = j+1

Expressions

  • Use != not <>
  • Don't compare boolean values to True or False using ==

No: if greeting == True:
Yes: if greeting:

  • Use parentheses to indicate the precedence of operators in complex expressions

Comments

  • Put comments on their own line before the code to which it applies
    • No inline comments
  • Indent comments to same level as the code to which it applies
  • Always keep comments up to date
  • Delete obsolete comments
  • Don't comment out code, remove it
  • Refrain from abusive comments

Naming

Unit tests

All classes should have test cases written for them. Even if it doesn't actually test anything but just exists, it's good to have the test there so there's a place to add more tests later.

Python Specific

Naming

  • Callbacks should be called cb_<name of event or signal>
    • NB: PyLint allows unused args in functions beginning cb_
  • trailingUnderscore_: to avoid conflicts with Python keyword
  • Exception classes should be called *Error

Documentation Strings

  • Every function should have a documentation string
  • See PEP257
  • Triple double quotes (""") are always used for docstrings.

Error Handling

  • Name the exception you're catching

Imports

  • Imports should always happen at the top of the module
  • Import one module per line, i.e. not import urlib2,xdrlib,HTMLParser, but it is ok to have from urlib2 import urlopen, urlretrieve
  • Try to avoid from module import *
  • import eXe modules with full library paths, e.g.

from exe.webui.element import getUploadedFileDir not from element import getUploadedFileDir

PyChecker?

All code should pass through Pychecker without generating warnings (although warnings from included third party libraries can't be helped)

Code

Use the log module to its fullest; when you need to print some values to debug, use self.log.debug to do so, and leave those print statements in the code (commented out) so they can later be re-enabled. Remember that once code is buggy, it tends to have more bugs, and you'll probably need those print statements again.

Javascript Specific

Even though JavaScript is a programming language in its own right, many programmers seem to forget about coding standards with JavaScript. In general, follow the same coding guidelines as you would with Python.

File structure

  • Place JavaScript in separate ".js" files. Reference them from the XHTML file used in.

Syntax Conventions

  • Use a semicolon at the end of each statement. JavaScript does not require a semicolon at the end of a statement if it is on its own line. Semicolons should always be used for readability, consistence, and ease in debugging. a=3; NOT a=3
  • Use single quotes for string literals so HTML attributes may use double quotes
  • Consider using the <noscript> tag to provide alternative text for JavaScript disabled browsers