Programming: Commenting

TODO: Is this section needed? This might fall under "common knowledge" to be expected of devs, i.e. not worth having a page about

When the code is not straightforward, please comment it to improve maintainability:

• When a piece of code is fixing a notable issue and the usefulness of the code is not obvious (this happens), you can add a comment that refers to the github issue ID:

# smooth segmentation (jcohenadad, issue #613)
sct.run('fslmaths segmentation.nii.gz -kernel sphere 3 -fmean segmentation.nii.gz')

Also, don't forget that the git commit history contains the "rationale" for every line of code in the project. You can use git blame to see who worked on a specific line of code, when and why:

• Who and when:

git blame -- scripts/sct_utils.py

ba39cd2a0 (George              2017-03-21 22:42:51 -0400  924) #=======================================================================================================================
ba39cd2a0 (George              2017-03-21 22:42:51 -0400  925) # delete_nifti: delete nifti file(s)
ba39cd2a0 (George              2017-03-21 22:42:51 -0400  926) #=======================================================================================================================
550b80425 (Julien Cohen-Adad   2014-08-14 13:12:28 -0400  927) def delete_nifti(fname_in):
550b80425 (Julien Cohen-Adad   2014-08-14 13:12:28 -0400  928)     # extract input file extension
550b80425 (Julien Cohen-Adad   2014-08-14 13:12:28 -0400  929)     path_in, file_in, ext_in = extract_fname(fname_in)
550b80425 (Julien Cohen-Adad   2014-08-14 13:12:28 -0400  930)     # delete nifti if exist

• why:

git show 550b80425

[...]