Templates and guidelines for coders

Thank you for contributing your work and time to the ORMIR community!

On this page, you will find templates, coding guidelines, and tips and tricks. Please, follow them to ensure that your code aligns with the existing code in the community and future contributions.

Don't forget to write code documentation! Code without documentation is rarely reused and hard to understand. Documentation is just as important as code itself!

Templates

Download the templates for coding and documentation. We are working on creating more and more!

Guidelines

Here are the coding guidelines of the ORMIR community:

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

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 result = var * 5

  • Leave space after a comma:

    var1, var2 = get_values(num1, num2)

Comments

  • Comments are introduced by #, positioned above the code they refer to, and 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. Be generous and precise with your comments!

We use docstrings (documentation strings), which are strings that describes a module, function, class, or method definition). We follow the NumPy guidelines.
Example: docstring for functions (for modules, classes, and methods, refer to the NumPy guidelines): 
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

Explanation: The function documentation is right below the function header, and it is between three opening and three closing single quotes ''' or double quotes: """. It is composed of 3 parts:

  1. Description of what the function does. It is written right next to the opening quotes

  2. Parameters, i.e. inputs of the function. It contains:

    • Parameters as a title, underlined by minuses

    • A list of parameters. For each parameter, we write:

      • Parameter name, colon (:), and parameter type (string, list, ITKimage, etc.)

      • On the following line, indented description of the parameter

  3. Returns, i.e. outputs of the function. It contains:

    • Returns as a title, underlined by minuses

    • The list of returns, using the same structure as for parameters

    • Special cases:

      • It the function does not return any variable, we omit the whole Returns section

      • If the function does not return a variable but the output of another function, we omit the variable name, as in this example:

    Returns ------- int
                                                            Integer component of the variable float_variable

  • Why is documentation important? Because docstrings are used:

    • By users to know what the function does by typing help (my_function)

    • To create whole code documentation using, for example, pydoc or Sphinx, where you get a list of all the functions in a package, and their documentation

ChatGPT! Example of command:
write docstrings in Numpy style for the following function: [paste your function]
Important: Double-check the content of the ChatGPT output!
For code: For data or publications:
  • You can use a Creative Commons license. Possibilities are: CC0, CC-BY, CC-BY-NC, CC-BY-NC-SA, and their combinations. If you are not familiar with Creative Commons licenses, you can browse the Creative Commons website or watch this video (up to minute 4)
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.
We created a GitHub readme template that you can download here. Just like for Jupyter notebooks, a readme file template allows us to harmonize our repositories and make sure we remember to include authors, licenses, use-cases, references, etc.
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 the ChatGPT output, preferably with test functions.
If you don't know Python: team up with some community members who know Python and work on the translation together!
  • Our pipelines usually start with .dcm images for CT/MR acquisitions or .isq images for µCT/HR-pQCT acquisitions.
  • Images are then transformed into other file formats for simplicity (e.g. nifti, metafile, etc.)
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 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.