This month’s issue of MSDN Magazine had a great article from Peter Gruenbaum titled A Coder’s Guide to Writing API Documentation. Let’s face it, documentation of the code we write is typically an afterthough, rarely given the attention it deserves, and is the first thing we point to (when it is lacking, that is) to complain about the ramp up time required for supporting a system.
I particularly liked one table Peter included in his article that laid out some basic guidelines for structuring documentation according to the type of code snippet we are annotating. I think by following these simple guidelines, any developer can have a big impact on their codebase.
| Type | Guideline | Examples |
| Class | Start with a word like “Represents” | “Represents a user’s photo album.” |
| Methods and functions | Start with a verb | “Returns the number of contacts for the specified area.”
“Pauses the video.” |
| Properties | Use a noun or start with verbs such as “Gets” or “Gets and sets” | “The user’s tasks.”
“Gets and sets a collection of the user’s tasks.” |
| Events | Start with a phrase such as “Raised when” or “Occurs when” | “Raised when the response from server is received.” |
| XML elements | Use a noun-based phrase | “The city’s postal code.” |
| Boolean values | For Boolean properties, start with “Indicates whether”; for Boolean return values on methods and functions, start with “Returns whether” | “Indicates whether the control is visible.”
“Returns whether two regions intersect.” |
I am a well documented fan and stickler for good commenting in code. I have been in too many organizations that refuse to make time or priority to do the necessary effort, but then love to complain when it isn’t sufficient. By using these basic guidelines, it seems reasonable that at least every public class, property and method can carry some descriptive notes that will aide the next developer who consumes those assets.
Start small, and I’m sure you’ll find that it has a big impact later on. Future ranks of developers who inherit your code will undoubtedly thank you for your diligence.
Leave a Reply