Skip to content

Variables

Jump to bottom
Yang Ding edited this page May 28, 2021 · 7 revisions

Bash

Bash Variables

In general, add prefix to variable names to help denote its type. For example:

path_input
path_seg
path_output
im_input
im_seg
im_label

Usage

Please use Python's argparse. If you need to reformat the usage text in order to display a list of items within certain flags, use formatter_class=argparse.RawDescriptionHelpFormatter. When you do so, please make sure to add return carriage before reaching 100 characters. This is the establish minimum Terminal width when using Ivadomed.

Flags

N.B. Rule: use "-" instead of "_" for separating words. E.g.: -init-mask

If-Statements

On bash there are different ways to write if statements, with single square brackets or with double square brackets.

The preferred way to do it is with double square brackets. See the example below.

foo="yes"
if [[ $foo ]]; then

fi

Python

Python Variables

For iteration, use i followed by meaningful character. Example, if you loop across z, then call your iterative variable iz.

In general, add prefix to standard variable name to help clarify the content of the variable. For example:

path_*           string     "path_" prefix always refer to a DIRECTORY, e.g.: /users/john/data/. Example variable names: path_seg, path_output, path_data
file_*           string     "file_" prefix denotes file name only (NO EXTENSION, NO PATH). In a way similar to Python PurePath.stem
ext_*            string     "ext_" prefix stores the extension of the file/data, e.g.: nii.gz, similar to PurePath.suffix/suffixes
fname_*          string     This is equivalent of all three parts above: path+file+ext. E.g.: /users/john/data/my_file.nii.gz. AKA absolute path. 
ftmp_*           string     temporary file name with extension that is updated within the code. 
                              (E.g.: data.nii --> data_crop.nii --> data_crop_sub.nii)
im_*             object     "im_" prefix usually represent an 2D/3D image/data object: eg. im_input, im_seg, im_label
nii_*            object     "nii_" prefix represents nibabel image object, containing data. Eg: nii_phase, nii_segmentation
data_*           array      numpy array containing data of same object as its nii_* counterpart.  Eg: data_phase, data_segmentation
remove_tmp_file  int        defined by flag -r

Classes

class Param:
    def __init__(self):
        self.debug = 0
        self.remove_tmp_files = 1
        self.verbose = 1

File names

  • Use underscore to separate words, do NOT use capitals. Example: sct_split_data.m vs sctSplitData.m

  • Put the verb before the object: Example: get_data.py is preferred over data_processing.py

  • Be explicit.

    • Because it is much easier to guess intention of overly verbosely named functions than a function name like processing.
    • Ideally, a balance. When not sure, try to make it MOST specific and LEAST confusing.
    • It is also in general a lot easier to refactor/rename complicated variables (more likely to be unique) and less likely to be confused versus a short name like processing which can appear in MANY contexts and places.
    • Example: sct_register_to_anat_slicewise.sh is preferred over sct_register.sh

Type Hinting

  • Any new function you write/create/refactored/touched MUST have type hinting on them both for input and for output.
  • We will enforce mandatory type hinting checks at pre-commit stage once most of the code base has been covered.
  • This also leverage IDE to do fault checking and automated discovery of problems
  • All new PRs going forward as of 2021-05-01 are being checked for type hinting completion with extreme prejudice.

IDE

  • We do not discriminate against any particular IDE.
  • Most devs are either on PyCharm / Visual Studio Code / Atom / Sublime.

Keywords/Constants

  • No one likes magical numbers. If it is significant enough, build it its own keyword data/constant/enum class.
  • The general rule of thumb is if you grab any passer by and they don't know why you chose particular number/string/keywords and it is not immediately apparent, it should be in a class and referenced instead.
  • This is important especially in the future when the keywords/magical number gets updated/changed. Good luck string search replace common words like rate
Clone this wiki locally