Writing Clean Scientific Software

This presentation reviews clean coding strategies for students and scientists who have learned to program on their own without formal training. There are many pain points commonly associated with scientific software, such as lack of user-friendliness and difficult-to-read code. Many of these pain points exist because the de facto programming paradigm in scientific research is publication-driven development (PDD), in which software is written for the purpose of publishing another research article at the expense of long-term software sustainability. These pain points make it harder to begin research and to collaborate with other scientists, and all too often make research frustrating. We can address many of these pain points by writing readable, reusable, and maintainable code. Variable names should be chosen to reveal intention and meaning. The length of a variable name should be measured not by number of characters, but by the time needed to understand its meaning. Decomposing large programs into smaller functions improves code readability, reusability, and testability. Functions should be short and do exactly one thing with no side effects. High-level big picture code should be separated from low-level implementation details, for example by writing code as a top-down narrative. Because comments often become out-of-date as code evolves, it is preferable to refactor code to improve readability rather than describe how it works. Well-written, automated tests increase the flexibility of code. Tests should be run frequently so that we can find bugs as soon as we introduce them. In summary, we should think of code as communication.This work was created with support from National Science Foundation (US) grant 1931388 to the Smithsonian Astrophysical Observatory. Many of the suggestions described in this presentation were adapted from the references linked to in the slides. A minor portion of this presentation was adapted from the paper entitled "Best Practices for Scientific Computing" by G. Wilson et al., which is available under the Creative Commons Attribution 4.0 International (CC BY 4.0) license