Skip to Main Content

Code Sharing

Code sharing for openness, reproducibility, and learning

Writing good code

Outside of the style guides for your computational language of choice, there are many resources on writing clean, well-documented, reusable code customized for researchers who are not professionally trained software engineers.

Simple Software Engineering Best Practices

Use clear variable names

Variable names should be clear and distinct. Concise variable names may be unclear to a future reader of your code (including you) and having many similar short variable names introduces a risk of using the wrong variable unintentionally.

Don't repeat yourself (DRY)

In essence - anything done repeatedly should be made a function. Duplicating code makes it harder to maintain, as any change must be replicated everywhere the code has been copied. Seeing the same code block repeatedly also makes the code harder to read and distinguish what any one part of the code is supposed to do.

Levels of abstraction & the stepdown rule

Levels of abstraction, familiar to formally trained software engineers, may be a new concept for many writing code for their research.

Functions should only do one thing and do it all at the same level of abstraction. A code document should also begin with its highest level of abstraction, and work downwards from there. One metaphor likens it to reading a newspaper article - the headline and lede tell you what the article is about, and you find out more and more details as you read down the page.

Metadata and citability

While code documentation and metadata ranges from simple to complex and vary significantly by discipline. There are some efforts to homogenize this and best practices, such as those provided by the FAIR Biomedical Research Software Guidelines project, are to use at a minimum: