There are two principles that are essential to writing good computer code.

1. Computer code is a set of instructions to a machine: it must be correct (obviously !!).
2. Computer code is a document that communicates ideas to people: it must be easy to read.

⇒ Keep your code as simple as you can.

We report in this document common coding rules. Try to respect them, but be consistent with surrounding existing code.

• Always use English language in your commentaries.

• 80-characters width.
• No tabs, use spaces (copy and paste does not always keep the indentation, mix of tabs and spaces causes syntax errors)
• indentations are 4 spaces

• Separate words in names with underscores.
• No mention of type in the variable name, especially no Hungarian notation.
• No abbreviations in names.

• If you work on existing code, respect the existing format.

• Always check parameter validity.
• Use the most descriptive type (for typed language).
• Use the minimal visibility (avoid global variable).
• Anything that is not intended to be used as an interface should be hidden.

• Return useful information when something goes wrong (use specialised Exceptions).
• Use assertions to check logic validity of your code, and throw errors for user input invalid parameter.

• There should be one short and clear sentence that states what a program does.
• Design documents and use cases are nice.
• Avoid useless comments in the code: Code should be self-describing
• Document all hacks !!

• Add a license header in each source file

Please read first the “official” Python style guide written by the Python's author.

You can use tools like PyLint which analyzes Python source code looking for bugs and signs of poor quality.

For example, you can use and complete the following header:

# -*- python -*-
#
#       OpenAlea.MyModule: MyModule Description
#
#       Copyright 2013 INRIA - CIRAD - INRA
#
#       File author(s): FirstName LastName <firstname.lastname@lab.com>
#
#       File contributor(s):
#
#       Distributed under the Cecill-C License.
#       See accompanying file LICENSE.txt or copy at
#           http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html
#
#       OpenAlea WebSite : http://openalea.gforge.inria.fr
#
###############################################################################
 
"""
Write the doc here...
"""
 
__revision__ = "$Id: $"

Don't mix tab and spaces. For new project, use only spaces.

Add a Doctring for all classes and functions.

(see How to document python API)

Modules or packages

Module names are the same as the file name. Modules should have short, lowercase names, without underscore. Singular is better than plural.

Yes:

  import tree

No:

  import Tree 

For C/C++/Fortran extension modules embedded in a Python package that provide a more Pythonic interface, the C/C++/Fortran module has a leading underscore (e.g. _amlpymodule).

Class Names

Class names use the CapsWords convention.

 class Tree:
    pass

Class Methods and Function Names

Class methods and function names should be lowercase, with words separated by underscores.

 def this_is_a_function():
     pass
 
 class ClassName:
     def class_method(self):
         pass 

Exception Names

Use class naming convention with Error as a suffix.

  class VertexError(TypeError):
    pass 

Whitespace in Expressions and Statements

Avoid extraneous whitespace in the following situations:

• Immediately inside parentheses, brackets or braces.

# Yes:
spam(ham[1], {eggs: 2})
# No: 
spam( ham[ 1 ], { eggs: 2 } )

• Immediately before a comma, semicolon, or colon:

# Yes: 
if x == 4: 
    print x, y; x, y = y, x
# No:  
if x == 4 : 
    print x , y ; x , y = y , x

• Immediately before the open parenthesis that starts the argument

list of a function call:

# Yes: 
spam(1)
# No:  
spam (1)

• Immediately before the open parenthesis that starts an indexing or

slicing:

# Yes: 
dict['key'] = list[index]
# No:  
dict ['key'] = list [index]

• Use spaces around arithmetic operators:

# Yes:
 
i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
 
# No:
 
i=i+1
submitted +=1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

• Don't use spaces around the '=' sign when used to indicate a

keyword argument or a default parameter value.

#Yes:
 
          def complex(real, imag=0.0):
              return magic(r=real, i=imag)
 
#No:
 
          def complex(real, imag = 0.0):
              return magic(r = real, i = imag)

Use property instead of get, set methods. Hide get and set methods with a leading underscore. Classes with properties have to inherit from object.

Yes:

  class Tree(object):
    def _get_root(self):
        return self._root
    def _set_root(self, _root):
        self._root = _root
    root = property(_get_root, _set_root) 

No:

  class Tree(object):
    def get_root(self):
        return self._root
    def set_root(self, _root):
        self._root = _root
    root = property(get_root,set_root) 

• Write warning free code. What generates a warning on one platform will generate errors on another.
• Don't use NULL for pointers. Use 0 instead.
• Don't compare == 'true' or 'false'. Use (x) or (!x) instead.
• Don't put an else right after a return.
• Use Doxygen markup language in any new class header files.
• Forward declare classes in your header files instead of including them whenever possible.
• Use smart pointers instead of raw pointers.

/* -*-c++-*-
 *  ----------------------------------------------------------------------------
 *
 *       VPlants.MyModule: : MyModule Description
 *
 *       Copyright 1995-2015 INRIA - CIRAD - INRA
 *
 *       File author(s): FirstName LastName <firstname.lastname@inria.fr>
 *
 *       File contributor(s):
 *
 *
 *       Distributed under the Cecill-C License.
 *       See accompanying file LICENSE.txt or copy at
 *          http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html
 *
 *      OpenAlea WebSite : http://openalea.gforge.inria.fr
 *
 *
 *  ----------------------------------------------------------------------------
 */

Indentation

Use 4 spaces per indentation level. Do not use tabs.

Functions

int fct( int i, int j )
    {
    // ...
    }

Loops

for( int i= 1; i <= n; ++i )
    {
    // ...
    } 

while( cond )
    {
    // ...
    }

do{
  //...
  }
while( cond );

1. PEP 8, Style Guide for Python Code
2. GNU Coding Standard
3. Mozilla Coding Style Guide