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