RAVEN Software Commentary Standard

RAVEN follows the Chromium commentary standard for Python code (see https://chromium.googlesource.com/chromiumos/docs/+/master/styleguide/python.md). Among the several rules, RAVEN strictly enforces the following:

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