-
Notifications
You must be signed in to change notification settings - Fork 133
RAVEN Code Standards
Code standards are important to maintain code readability and a reasonable similarity in branding throughout the code architecture. Here we outline the coding practices for the RAVEN project.
-
Use 2 spaces for each indent level. Use spaces, not tabs.
-
Function definitions should have at least one line of whitespace afterwards.
-
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 should be split if possible.
-
Class names should start with a
Capital
letter. Other variables should becamelBack
case. Underscores should not be used in variable names, except in the case of private and protected variable prefixes. -
Private variables start with two
__underscores
. Protected variables should start with one_underscore
.
-
except:
with no exception should only be used in extraordinary circumstances; instead something likeexcept KeyError:
orexcept Exception as e: print(repr(e))
would be better so only the provided exception is ignored or something is done with the exception.
- For python 2 code, it should have:
from __future__ import division, print_function, unicode_literals, absolute_import
import warnings
warnings.simplefilter('default',DeprecationWarning)
before any code to simplify porting to python 3. (Importing unicode_literals can be skipped if it causes problems and this is discussed with other developers.)
- Functions should have a docstring, which is right after the line defining the function and are between triple quotes """.
- The triple quotes should 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. - Each output should be listed similarly to the inputs, the line starting with
@ Out
, the name of the output variable, followed by the type of the output, and a brief description of it. The outputs must be listed in the order returned, and can be listed as a single returned tuple or on multiple lines if it can improve clarity. See examples below. 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 start of a function, method or class should use the # character to start them. Lines beginning with a
#
should be indented to match the line(s) of code they refer to.
Examples:
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, (x,result), tuple(float,float), original value and square of x
"""
result = x*x #square by multiplying
return x,result
def sqrWithMultOut(x=2.0):
"""
Returns the square of the argument.
@ In, x, float, optional, number to be squared
@ Out, x, float, original value of x
@ Out, result, float, square of x
"""
result = x*x #square by multiplying
return x,result
def printWolf():
"""
Print the message 'Wolf'
@ In, None
@ Out, None
"""
#prints "Wolf" to stdout
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
- The so-called "wild importing" approach is FORBIDDEN, i.e. :
from aModule import *
- Rather than editing the system python path to load modules, a hierarchal structure should be used. For example, instead of
sys.path.append('/path/to/moduleGroup')
import myModule
an effort should be made to make moduleGroup
a true module by including a __init__.py
file, then import by
import moduleGroup.myModule