Documenting My Code … For Me

There are two signs of old age:

Forgetfulness

and ….

…I forget the second.

Here’s some R code…

cnvmmdrtn <- function(mmfWtr) {
    return(mmfWtr * 271325622)
}

That was ugly

If you are reading this, you’re a coder and use functions. We write them for ourselves. If someone else writes a function, you can hope it works. If it doesn’t, you can hope to fix it. Hopefully, the return value is obviously correct. But maybe it’s subtly wrong?

If things are amiss, read the name of the function and hope it’s descriptive. I worked with a programmer who omitted all vowels from his function names. So the above code would expand to this…

conv_mm_to_duration <- function(mmOfWater) {
    return(mmOfWater * 271325622)
}

C is self-documenting

Another coder in this group believed C was a self-documenting language and he never included comments. At the time, I was a developer evangelist, supplying outside individuals and companies with documentation on how to use our code. I spent a lot of time talking to both programmers, untangling their code and explaining it to the outside world. The salary they paid me to reveal the inner workings vastly overshadowed the execution speed they gained by trimming vowels and omitting documentation.

“They get the correct number,” says the programmer. “Why do they need to know how it is obtained?”

“Irrigation systems have differing flow rates,” I reply. “It sure would be convenient if they knew the internals so they could adjust.”

“I can re-write the function to include a parameter to adjust the flow rate,” they said.

“That would be handy,” I say. “What would the function look like?”

It was weeks since our coder wrote this function, and they had forgotten the specifics. We spent a half hour sorting through old notes scratched out on recycled sheets of printer paper. (It’s before the days this group started using source code control.) We found this…

conv_mm_to_duration <- function(mmOfWater) {
  # how long to fill the volume with water?
  secondsOpenValve <- mmOfWater * 254 * 254 / .25 / 60 / 60 * 3.785e+6  

  return(secondsOpenValve)
}

That’s a start, but we’re still left puzzling out 254 used twice, .25, 60 used twice, and 3.75e+6. We had to go back and essentially re-write the function to understand the function.

Soapbox

I re-read what I’ve written so far and I think; “Nobody is going to read this. Nobody is going to care. Who doesn’t write documentation or document values?“

We assume that nobody else will view the code we write. We understand the logic and how it works, so why bother commenting on what we obviously know?

…And that is a path to madness. Please, for everything holy, write understandable code. You’ll thank yourself. I thank myself every time I re-open code from weeks ago.

Here’s the current implementation:

#' conv_mm_to_duration
#' 
#' Convert mm of water into number of seconds to run irrigation system
#'   Assumes a flow rate of .25 gallons per hour
#'
#' @param mmOfWater How many mm of water being called for. 
#'     An average garden requires 25.4 mm of water per week
#'
#' @return seconds to keep the irrigation valve open
#' @export
#'
#' @examples
#' conv_mm_to_duration(254)

conv_mm_to_duration <- function(mmOfWater) {
  # convert GPH to mm3/second
  emitterGPH <- .25
  
  # emitters put out .25 gph
  emitterGPsec <- emitterGPH / 60 / 60 # divide by seconds per hour
  mm3_per_gallon <- 3.785e+6
  emitter_mm3_sec <- emitterGPsec * mm3_per_gallon
  
  # calculate the volume to be filled with water
  emitterDistance_mm <- 254
  volumeToFill <- mmOfWater * emitterDistance_mm * emitterDistance_mm
  
  # how long to fill the volume with water?
  secondsOpenValve <- volumeToFill / emitter_mm3_sec
  
  return(secondsOpenValve)
}

Do you recognize the lines beginning with #’ ? Those are used by roxygen to generate documentation. Roxygen is convenient to use, but it isn’t the only solution. Check with anyone you’re working with and do the same thing. If you’re working alone, Roxygen isn’t a bad place to start.

Want to know more? There are plenty of advanced programmers who will tell you the same thing; The Product is Docs is an aging book but still provides a good basis for documentation and better programming.