Lynn YarmeyNational Snow and Ice Data Center

Version 1.0Review Date

Writing and Sharing Readable Code

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Overview

•Why is writing and sharing readable code important?

•Tips for creating readable code

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Why is code sharing important?

•Reproducibility of science•Someone else can build on your work•Get credit in NSF Data Management Plans for work you already do

“Much of the debate about code transparency involves the philosophy of science, error validation and research ethics, but our

contention is more practical: that the cause of reproducibility is best furthered by focusing on the dissection and understanding of code, a sentiment already appreciated by the growing

open-source movement.” (Ince, et al., 2012)

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Sharing your code

• Not at all

• With your advisor and lab

• By email if someone asks

• On your website

• Through an Institutional or Domain Repository

• As a publication

• see Open Research Computation Journal

• Through a code bank• Ex. Geophysics Source Code Archive

Lower

Higher

Funder Happiness

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Good coding practices

Sharing doesn’t help if no one can read or understand your code

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Tips for Readable Code

• Use logical, clear names for variables and subroutines

• Add explicit comments

• Be platform-independent where possible

• Document the connections to data sets (which code is applied to what data?)

• Use a consistent versioning method

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Header Information

• In the header, include:

• Author name

• Original creation date

• Latest revision date with code version number

• Software version number

• Short description of the code

• Long description of the code

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Resources

•Matlab Programming Style Guidelines

•Perl Best Practices

•R Coding Conventions

•And many others…

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

References

•Anel, Juan A. (2011). Importance of Reviewing the Code. Communications of the ACM. Volume 5 (May 1). Retrieved from: http://cacm.acm.org/magazines/2011/5/107698-the-importance-of-reviewing-the-code/fulltext

•Darrel C. Ince, Darrel C., Hatton, Leslie, & John Graham-Cumming. (2012). The case for open computer programs. Nature. 482, 485–488 (23 February). doi:10.1038/nature10836

Module Template: Subtitle; Version 1.0, Reviewed 9/15/11

Other Relevant Modules

•Data Management Plans