General Guidelines for Function Documentation

Also known as “methods,” “procedures,” “subroutines,” or even just “routines,” functions are the primary way we encapsulate executable code into reusable named blocks.

Functions have numerous things at an interface level that are important to document:

• A basic summary of what the function does.

• Any limitations/usage assumptions important correct use.

• Meanings/usage of parameters.

• Meanings/usage of return values.

• Meanings/usage of exceptions.

• Maintenance notes for future programmers.

Below is an example showing basic summary, parameter, and return documentation:

Documenting the Many Different Parts of Functions

Given how many different parts there are to functions, there are many things to consider when documenting them. The sections below go into details. They build off of each other, so you can see how some documentation evolves from the “minimum” for a function to encompass additional important information.