Good enough practices for sharing computer code in neuroimaging

How to make your code useful

This post called 'Good enough practises for sharing computer code in neuroimaging' is my take on 'Good enough practices in scientific computing' from Wilson et al. (2017) and 'Toward standard practices for sharing computer code and programs in neuroscience' by Eglen et al (2017). 

Before dwelling into practices, what do 'we' mean by useful?

Since one of the tenet of the scientific method is to be able to reproduce result, a useful code is going to be a code that allows to reproduce, at least, the main results of a study.

There are few other things that are useful beyond the realm of the scientific method .. it's the scientific work that we do: a useful code is a code that you can reuse yourself in 6 months, that somebody can reuse. By doing so it furthers the understanding of your work, and allow to improve and develop new code and methods. 

What Best practices?

In making code

Version control your code using e.g. git. This is useful in so many ways that I''m not going to explain it here - instead check this video.

Reusing other's code is absolutely fine but 'don't be a dick' as Cameron Craddock likes to say, that is cite them properly, and if you think there was a mistake in the initial code, have a little chat with the author(s).

Make lots of functions - it is recommended to have many small functions over making one huge one. This is much easier to understand what each chunk does and increases re-usability. It also makes it easier to test. 

Testing - if you never heard of it then it's a problem because it means you are likely suffering from confirmation bias, it doesn't mean your code is wrong though, There is however a better way to know that a function works than by spitting the expected results from experimental data. Basically the idea is that for bits of code you download or write, you have another bit of code that tests if does what it is supposed to do, for instance generate a simple data set knowing what the outcome is. For larger projects, there is also integrations tests, checking information flows properly between functions.

Documentation? well of course it's always better to have super documented code, but basics are - a header in each function that explains what is does, a readme file (txt or markdown) that tells what the overall code does and a requirement file  (txt or markdown)  that indicates all the dependencies, libraries, etc the code depends on.

In sharing code

Putting your code in a repository like github is useful, but typically it will be updated with time, It is thus recommended to post the code used for a study in a repository with a stable URL (e.g. zenodo, figshare, open science framework)

Add to the code/repository, a citation file which details how to cite your code or the paper corresponding to that code.

Don't forget to include a license file, I like CCBY but BSD and MIT are also recommended. Avoid CCNC as the non commercial close can really limits the impact of your work. More details on this from my favourite institute here SSI and of course choosealicense.com.