Originally published by Robert Beisert at fortcollinsprogram.robert-beisert.com

Patterns: The Documentation Contract

When you commit to a set of documentation, you are telling all the users how your code will work and how they should use it. This has a trickle-down effect, such that any changes to the documented features can destroy entire suites of programs.

Violation of the Rule

Suppose you provide documentation for an early-release form of your code. Other teams and other companies start working your function calls and structures into their code. Perhaps these new codes are built into libraries, which are used to build large distributables.

Then you add just one parameter to one major function. It’s mostly harmless, right?

Unfortunately, you just broke everything.

Now the groups that were using your code have to go through the entire design process again. They have to update all of their code to match your new definitions, and then they have to test everything to make sure it still works. Your 15 second change results in tens (or even hundreds) of hours of work across the board.

Adherence to the Rule

There are several ways we can preserve the documentation contract.

  1. Employ modular design principles. All additions to the documentation are new modules, while the old modules remain intact. This allows your end-users to decide whether to accept your changes or not.
  2. Hide what you’re doing. If you leave the function interfaces alone, you can make changes to the functionality without necessarily informing the end-users. This only really applies with runtime libraries, though.
  3. Build from wide to narrow. Just like a pyramid, you start with functions that take all the arguments you can possibly think of. Then, you tighten the focus with each new function until you have the minimal function. This pattern is extremely useful when you have default inputs but you still want to be able to change those defaults if desired.

Lesson: Your Documentation tells the world how to use your code. Make sure that you preserve the documented functionality and interfaces.

photo by: