Proposed standards for peer-reviewed publication of computer code

Authors: Timlin, Dennis; DAVID, OLAF - Colorado State University; Green, Timothy; Fleisher, David; KIM, SOO-HYUNG - University Of Washington; Ahuja, Lajpat

Submitted to: Agronomy Journal
Publication Type: Peer Reviewed Journal
Publication Acceptance Date: 4/16/2016
Publication Date: 7/20/2016
Publication URL: http://handle.nal.usda.gov/10113/5508062
Citation: Timlin, D.J., David, O., Green, T.R., Fleisher, D.H., Kim, S., Ahuja, L.R. 2016. Proposed standards for peer-reviewed publication of computer code. Agronomy Journal. 108:1-5. doi: 10.2134/agronj2015-0481

Interpretive Summary: In order to understand and assess biophysical systems such as plant growth, soil and watershed processes or cropping systems, mathematical models are often used by scientists. These models are known as abstractions of the physical systems because the system is represented as a compilation of mathematical equations and not the actual objects themselves. Because computers are good at repeatedly calculating results of mathematical equations, these models are often written as computer code. These models are scientific products and represent long periods of research and development. They are also subject to change as our scientific knowledge of physical systems improves. Therefore, it is critical that the software used to code these models be well documented, and written in a clear, easily understandable format. The goal of documenting source code is to inform the reader of the logic, meaning of variable names, and purpose of the various components of the code. Users, not familiar with the code, should be easily able to comprehend and use it. In this paper we investigate and describe the goals of software documentation and the best way to meet those goals. Well documented computer code will insure that the code can be reused by both the developers and other users therefore insuring that the investment in the research used in the model is well used. This paper is useful to scientists and other developers who write or use computer code in their work.

Technical Abstract: Computer simulation models are mathematical abstractions of physical systems. In the area of natural resources and agriculture, these physical systems encompass selected interacting processes in plants, soils, animals, or watersheds. These models are scientific products and have become important in both research and education, and their usage is not limited to the developers but can be expanded to a wide range of potential end users. The models are also subject to change as research increases our understanding of the modeled processes. Therefore, it is critical that the software used to code these models be well documented, and written in a clear, easily understandable format. The goal of documenting source code is to inform the reader of the logic, meaning of variable names, and purpose of the various components of the code. Users, not familiar with the code should be easily able to comprehend and use it. The documentation should include test data and a driver such that users can run the model and compare output to published results. Parameters, and input and output variables, should be described in detail, and parameters documented so their source in the literature can be identified. A large amount of resources and research are invested in computer models. Use of models by members of the scientific community and other end users can increase the impact of the developer’s research. Also, reuse of code can reduce costs of research devoted to modeling efforts. This paper investigates necessary requirements to document code to facilitate the use and modification of code by both developers and those interested in furthering research.