No Need for Excuses: Applying Software Engineering Principles to Facilitate Scientific Software Documentation, SIAM CSE19, Spokane, Washington, Minisymposterium: Software Productivity and Sustainability for CSE and Data Science

Software documentation improves qualities such as maintainability, reusability, verifiability and usability. So why do scientific software developers underemphasize documentation? Reasons include: i) requirements are not known up-front (they emerge over time), ii) change is frequent, iii) rigid processes hamper creativity, iv) the software is too complex; and, v) there is no test oracle. These are reasons that documentation is challenging, not excuses for avoiding it entirely. Complexity and frequent change are not unique to scientific software. So how do other domains deal with these challenges – by applying Software Engineering (SE) principles, techniques and tools. Specific SE ideas helpful to scientific software include: faking a rational design process, documentation templates, abstraction, anticipation of change, generality, replicability, separation of concerns, information hiding, and tool support. Many developers are familiar with these ideas, but examples of adapting them to scientific software are rare. An example is shown here to illustrate SE ideas applied to software to analyze the solidification of a molten metal alloy.