Proper Documentation: Avoiding Spaghetti Code
My wife is a nurse, and she lives by the adage “if you didn’t document it, you didn’t do it.” Obviously, this is an understandable sentiment in the life-and-death world of the medical field. Why is it, though, that programmers regularly appear to feel that documentation takes a back seat to just about everything else? In an industry where employees seem to change jobs about as often as they change their shirt, too many coders leave their replacements banging their heads against the wall by providing minimal documentation, if any.
Producing quality documentation is a top-to-bottom methodology that begins with the proposal and continues through to delivery. A professionally-developed proposal should include a detailed specification sheet (often called a “spec” or “spec sheet”) that outlines the exact requirements, milestones, and performance metrics for a given project. Starting out with a well-produced document of this nature can serve the needs of the programmer as well as the client. By providing a road map for development, any changes from the original design can easily be tracked and costs can be renegotiated as appropriate.
Documentation isn’t just a separate file to be turned in with the other deliverables. It extends to the way code is shaped. Not everyone agrees with the school of thought that recommends camelCaseNamingConventions, but whatever system is being used to create class, method, or property names, their respective functions should be apparent at a glance. Too often, coders will use variable names that mean something only to them, or substitute names such as “foo” during prototyping, only to leave these stand-ins hanging around in the final product. Code should maintain a consistent method of indentation as well as methodology. If a specific method uses a while loop, for example, to complete a task, then a similar function should not use a for loop unless it’s strictly necessary. Maintaining consistency helps future programmers read code more easily.
Speaking of classes, methods, and properties, object-oriented code tends to be easier to read than procedural code for most medium-to-large scale projects. Programmers should consider using this broadly-adopted form of coding for nearly any project beyond the most simple of hacks. Unless the client specifically requests that the coder avoid the practice, documentation should be added before each class or method to explain the general purpose of each.
At the close of a project, a functional document should be presented to the client that outlines each class and method. This document can then be referred to at a later time by the original programmer or by his or her replacement. If the coder has documented the code properly, the same text can often be used in the functional document, simplifying the process.
Writing clean and well-documented code is a great way to be recognized as a professional, as well as a good reason to be recommended to other clients. The coding world is often bereft of programmers who not only talk the documentation talk, but walk the documentation walk. Standing out from the pack in this way is never a bad thing.
SPECIAL BONUS THIS WEEK
I am providing two documents I have used with clients for your education and use. Please refrain from copying these documents verbatim, but feel free to use them as you see fit otherwise.
The first document is a proposal for a network of interlinked sites that “funnel” traffic to a specific source. I called it “owning the pipeline” because I thought at the time that would be a clever name. Click the document’s name to open it (PDF format).
The second document is a spec sheet for an accounting system. This was an actual project, but the names have been changed to protect the innocent. Click on this very hyperlink to download the document.
