Coding guidelines

Here are our guidelines for code, data, and publications

Python code

We follow the Style Guide for Python Code. In summary:

Naming Style
  • Variables, functions, methods, modules, packages:
    lower_case_with_underscores
  • Constants:
    ALL_CAPS_WITH_UNDERSCORES
  • Classes and exceptions:
    CapWords

Indentation
  • 4 spaces or 1 tab

Space
  • Leave space between operators in case of assignment and arithmetic operations:
    var = 4
  • Leave space after a comma:
    var_1, var_2 = get_values(num_1, num_2)

Comments
  • Comments are introduced by # positioned above the code they refer to, and they are indented to align with the code are commenting on:
    # assign variable
    a = 5
    Why are comments important? As part of a community, we want to write code that can be readable and reusable by others. Let's be generous and precise with our comments!
If you already know Python: ChatGPT! Example of command:

translate the following code from Matlab to Python: [paste your code]

Important: Double-check the content of ChatGPT output!

If you don't know Python, team up with some ORMIR community members who know Python and work on the translation together!

Python documentation

We use Numpy style docstrings to document our code. Docstrings describe functionalities and parameters of the subsequent code and are enclosed in triple quotes ("""..."""). They are typically placed at the beginning of the module, class, function, or method they describe. Here is the example of Numpy style docstrings for functions:

def my_function (input1, input2):

    """This functions does ...

    Parameters
    ----------
    input_1 : type
        Description of the parameter `input_1`
    input_2 : type
        Description of the parameter `input_2`

    Returns
    -------
    output: int
        Description of the variable `output`
    """

    # function body
    return output


The documentation is between the header and the body, and it contains at least the following sections:
  • Description: An explanation of what the function does
  • Parameters: A description of each parameter the function accepts, including name, data type, definition, and default values
  • Returns: A description of the values returned by the function, including name, data type, definition, and any special cases
You can find a complete description of Numpy style docstrings on the Numpy website
With ChatGPT! Example of command:

write docstrings in Numpy style for the following function: [paste your function]

Important: Double-check the content of ChatGPT output and correct wherever needed!
Read the Docs is a tool to genereate code from docstrings and to host and publish documentation on the web. To learn how to use Read the Docs follow their step-by-step tutorial. An excellent example of Read the Docs is the documentation of Ciclope.
Sphynx is a tool to write and generate documentation from docstrings. You can find guidelines on how to use Sphynx here

Code license

You can choose a permissive license (e.g. BDS, MIT, Apache) or a copyleft license (e.g. GNU GPL, Mozilla). If you are not familiar with open-source licenses, you can browse choosealicense.com, read the paper A Quick Guide to Software Licensing for the Scientist-Programmer, or watch this video (from minute 4)

Jupyter notebook

Jupyter notebooks are useful not only to draft code, but also to create use cases, demos, or examples for Python packages
We created a Jupyter notebook template that you can download here. Just like when you write a paper, you fill out a journal template with your content, you can fill out the ORMIR community notebook template with your narrative and code.

Why should I use the template? We usually use notebooks to create use-cases for our Python packages. Using the template allows us to harmonize our use-cases and to make sure we remember to include authors, licenses, references, etc.

GitHub

We created a GitHub readme template that you can download here. A readme file template allows us to harmonize our repositories and make sure we remember to include all sections, such as authors, licenses, use-cases, references, etc.

Data

Our pipelines usually start with .dcm images for CT/MR acquisitions or .isq images for ┬ÁCT/HR-pQCT acquisitions. We recommend to organize image files and folders following the ORMIR-MIDS specifications implemented by the ORMIR-MIDS Python package.

Publishing

Consider publishing in the Journal of Open Source Software (JOSS). The paper is only a few pages and reviewers check your repository, helping you improve it.
To get a permanent Digital Object Identifier (DOI) for your code so that it can be referenced, you can link your GitHub repository to Zenodo. You can find instructions on this webpage or in this video.

Do you have some questions that we didn't address? Contact us!