Detailed Documentation as a Deterrent to People Screwing Up Perfectly Good Code

A common problem when working on a project where multiple programmers make modifications to the same codebase, especially when some of those programmers are of the 'code monkey' variety, is that originally well-written classes and functions are modified by people other than the original author to handle tasks they weren't designed for and otherwise behave in silly ways, leading to a project full of unnecessary coupling, redundancy, and bugs. I have found that extremely detailed documentation can help alleviate this problem in a few ways. Here's how it works:

Document the purpose of every property, every method, every argument, and every return value for non-trivial classes and functions, even if the purpose is relatively clear given the names and code involved. Include in the documentation descriptions of how functions should be used and how the arguments and return values relate. If there are fields that should only be modified when setting up an object, or only by a certain thread, say so.

The most obvious benefit is that a mediocre programmer who might otherwise have misunderstood how something works has a human-readable description to help educate them. Maybe they would otherwise have hacked some unrelated feature into an otherwise elegant function, but will be deterred when they understand the purpose and the reasoning that went into creating it. If there is a bug in the function or a new feature that must be added, they will have a better idea of how to make it fit within the existing architecture, since they have a better idea of what that architecture is.

Crap coders pose a different problem. No amount of documentation is likely to dissuade them from making a mess. They might not read the description, or they might read it but, not recognizing their own lack of understanding, decide that they know better. They will munge your function in whatever godawful way their randomly-firing neurons lead them to. But when the system starts crapping out and you follow the trail of commits back to the change, the original documentation (easily distinguished from any changes, which, if they exist, will lack proper spelling and punctuation) will tell you what this part of the program should really be doing, making it far easier to repair.

About the Author

Everybody sucks except me (and Jared).