Types of Codes

As discussed, you should use a software release any time you write new code. As such, software releases encompass a wide variety of codes, with varying purposes and complexities. It is often useful to keep the purpose of your code in mind, as this helps determine the criteria used to review your code as you develop it. This page describes several common types of codes, with the intent of establishing a common vocabulary for later discussion. As you read, try to determine which description(s) most closely match your own code.

flowchart TD subgraph reuse ["`**Reusable Code**`"] direction LR a[More generalized] b[Intended for reuse] end subgraph reference ["`**Reference Code**`"] direction LR c[Documents your work] d[Supports a publication] end

Summary of reference and reusable codes.

Reference Implementation

Reference implementations are common codes for scientific research. Typically, a reference code accompanies a published manuscript and is used to show the author’s work. Essentially, the code documents one or more computational analyses, for the purpose of open and transparent science. The purposes of these codes may include (but are not limited to):

  • Pre-processing input data

  • Running simulations or models

  • Conducting mathematical analyses, and

  • Producing figures

As stated, reference codes are intended to document the steps of a published analysis. They should reproduce the analysis if re-run, but running the code multiple times is typically not the main intent. As such, reference codes do not need to be optimized for fast runtimes or modularized for general use. However, a reference code must be readable. An interested scientist with a basic introduction to the relevant coding language should be able to understand the code’s steps with minimal effort. As such, reviewers should focus on the readability and clarity of the code.

Reusable Tools

On the other end of the spectrum are codes intended as reusable tools. These codes typically include more generalized routines that may be suitable for a variety of scenarios. Two common examples are software libraries and operational tools. An operational tool typically implements a specific task or analysis in a generalized manner. As such, the task can be implemented for a variety of scenarios. Examples of operational tools for LHP include:

  • flowalert: code that monitors rainfall for potential landslide triggers

  • Codes generating post-fire debris-flow hazard maps

By contrast, a software library provides a collection of useful routines related to a particular subject area. Unlike an operational tool, a software library is usually intended for a variety of purposes, which can be accomplished by combining the library utilities in different ways. Examples of well-known libraries include:

  • numpy: A Python library with functions for numerical computing,

  • tidyr: An R library with utilities for cleaning data

and LHP libraries include:

  • digger: A collection of utilities for file IO with D-Claw

  • pfdf: Utilities for analyzing post-fire debris-flow hazards

In reality, most reusable tools will fall somewhere in the middle, and the examples here are no exception. This is fine, and it’s mostly the reusable nature of the tool that matters for this guide. Since reusable tools may be used multiple times in a variety of settings, these codes will typically have stricter standards than reference codes. For example, reusable tools should usually include testing suite to demonstrate that they work as intended. More details on reviewing reusable tools can be found on the Code Review page.