Document Why, Not Just How or What

March 1, 2011

Chapter 8 – Open Teams

Documentation is vital to the completeness of any coding project. If your code doesn’t have documentation, then it isn’t done. Most coders are good at documenting how things work. You will see a lot of comments like, “added a new method to the API” and “iterate over these values to find the one we are looking for.” These comments are useful because they make the code more readable, but they don’t tell the whole story.

Don’t restrict your documentation to code comments. You have many opportunities to talk about your code like check-in comments, bug comments, and design documents. Take advantage of them.

Previous post:

Next post: