RAVEN Software Coding Standard

RAVEN follows the Chromium coding standard for Python code (see https://www.chromium.org/chromium-os/python-style-guidelines). Among the several rules, RAVEN strictly enforces the following:

General coding standards

• Use 2 spaces for each indent level.
• Class names should start with a Capital letter.
• Other variables should be camelBack case.
• Private variables start with two underscores: __
• Protected variables should start with one underscore: _
• Function definitions should have at least one line of white-space afterwards.
• except: with no exception must never be used
• In order to be compatible with Python 3.x releases, any Python 2.x code, must have:

from __future__ import division, print_function, unicode_literals, absolute_import
import warnings
warnings.simplefilter('default',DeprecationWarning)

before any code.

• The so-called "wild importing" approach is FORBIDDEN, i.e. :

from aModule import *

• Multiple statements on one line are not allowed. For example the following is forbidden:

if makeAnimal: self.raiseAMessage("we just increased the MOOSE herd population")

and should be changed to:

if makeAnimal: 
  self.raiseAMessage("we just increased the MOOSE herd population")

• Tuple unpacking and packing should only be used when needed. For example:

a, b = 0, 1

should be rewritten to be:

a = 0
b = 1

However, using it for function returns and swapping is allowed, since it saves temporary variables:

a, b = b, a

or:

a, b = funct()

are allowed.

• Lines longer than 120 characters must be split.

Commentary standards

• Functions must have a ​docstring, which is right after the line defining the function and are between triple quotes """. * The triple quotes must be on their own line, and an additional level of indentation should be provided for the documentation comments.
• Each input should be listed in the fashion below, starting with @In, then the name of the input, the type of the input, (optional) and a brief description.
• For output variables, the line starts with @Out, the name of the output variable, followed by the type of the output, and a brief description of it.
• In the event the return object is not a named variable [and it is not possible to do so (e.g. the method is very short and an addition of a named variable does not represent an added value for the readability of the code)], the name of the method should be listed instead.
• Other comments not at the begin of a function, method or class should use the # character to begin them. For example:

def sqr(x):
  """
    Returns the square of the argument.
    @ In, x, float, number to be squared
    @ Out, result,float, square of x
  """
  result = x*x #square by multiplying
  return result

def sqrWithOptionalArg(x=2.0):
  """
    Returns the square of the argument.
    @ In, x, float, optional, number to be squared
    @ Out, result,float, square of x
  """
  result = x*x #square by multiplying
  return result

def printWolf():
  """
    Print the message 'Wolf'
    @ In, None
    @ Out, None
  """
  print("Wolf")

def returnSize(x):
  """
    Return the size of an array
    @ In, x, numpy.array, the array whose size needs to be determined
    @ Out, returnSize, int, the size of the array 'x'
  """
  return x.size