| |
Don't Forget the Internal Software Documentation
By V. Berba Velasco Jr., Ph.D.
Internal documentation. It's one of the most frequent casualties in software development.
It's not hard to see why. For most companies, time is money, and they frequently find themselves scrambling to release a product. It can therefore be tempting to save time by cutting corners—by shortening or eliminating development stages that appear to slow down the coding process.
Many programmers scoff at the importance of this documentation. “I know what I'm doing!” they say. “Time is short, and writing about my work will only slow things down. Besides, if something goes wrong, I know that I can fix it.” This is a terribly naïve and short-sighted approach. Such a cavalier attitude toward documentation can be disastrous to a company's future.
It doesn't help that programmers and engineers are notorious for having lackluster communication skills. It doesn't help that documentation is a task that they seldom enjoy. The result is often an intractable mess—utter software design chaos.
A naïve programmer may think, for example, that in-code comments are unnecessary. I remember one engineer who laughed out loud when he saw me inserting comments into my code. “Look at this guy!” he chortled. “What a waste of time!” Admittedly, few programmers would carry this attitude to such an extreme; however, such perspectives are still implicit to a great many software developers.
It's not just in-code comments that are important. In general, one should also document general software architectures, detailed designs, flows of logic, installation instructions, and so forth. The exact requirements will naturally vary depending on one's specific situation, but as a rule, these are helpful benchmarks to strive for. The act of writing these documents can be tremendously helpful in guiding one's design process, and it can provide helpful tools for design reviews and peer feedback. In addition, the developer's goal should be to ensure that future programmers can figure out how it works without a great deal of hand-wringing or gnashing of teeth.
Unfortunately, many employees take the opposite viewpoint, and purposely scrimp on the documentation. Often, they do this to ensure job security for themselves—and sometimes, this tactic works. By scrimping on documentation, however, he may wind up jeopardizing the company's long-term success. Besides, an astute employer knows that an programmer who documents well is worth far more than someone who holds his cards close to his vest. The latter may seem valuable in the short term, but ultimately, he's a long-term liability.
So if time is short, please resist the urge to cut corners when it comes to software documentation. This may seem like a good way to save development time, but the results are bound to be disastrous.
About the Author
V. Berba Velasco Jr. has been developing software for nearly twenty years. During that time, he has repeatedly discovered value of judicious software planning and design. Dr. Velasco currently serves as a senior electrical and software engineer for Cellular Technology Limited (www.immunospot.com, www.elispot-analyzers.de, www.elispot.cn) , a biotechnology firm in Cleveland, Ohio.
Article Source: http://www.simplysearch4it.com/article/1133.html
| If you wish to add the above article to your website or newsletters then please include the "Article Source: http://www.simplysearch4it.com/article/1133.html" as shown above and make it hyperlinked. |
| Some other articles by V. Berba Velasco Jr., Ph.D. | Using 'Get' and 'Set' Might Be Something You'll Regret
It's an all-too-common pitfall. Programmers who attempt to write object-oriented code decide to make all of their data variables private, ...
People Who Think They're Right
A few months ago, I had a conversation with a churchgoer who complained about religious intolerance. He said (and I paraphrase), "When ...
A Common Misconception about Object-Oriented Programming
I've seen it time and again. A computer programmer proudly proclaims, "Yeah, my code is object-oriented. See? My data members are all private, and they can only be ...
Listening Techniques For More Effective Meetings, Part II
In Part I of this article, we discussed the importance of active listening, and how it is important for smooth and effective meetings. In the ...
Listening Techniques For More Effective Meetings, Part I
We all know what it’s like when a meeting doesn’t go smoothly. Discussions get derailed, tempers start to fray, and things are seldom resolved ...
A Time-Saving Programming Tactic That Doesn't Work
Let's say that you have a software project that's under severe time pressure. Let's say that this deadline is so tight that you already know it will involve many late nights of black coffee ...
|
|
| |
|
