Documentation As a Bug-Finding Tool 188
New submitter Sekrimo writes "This article discusses an interesting advantage to writing documentation. While the author acknowledges that developers often write documentation so that others may better understand their code, he claims documenting can also be a useful way to find bugs before they ever become an issue. Taking the time to write this documentation helps to ensure that you've thought through every aspect of your program fully, and cleared up any issues that may arise."
Re:Common knowledge? (Score:5, Interesting)
Just as often, while writing documentation on code I just wrote, I've thrown up my hands, and thought "this is so ridiculous and embarrassing that I can't be associated with it", and I went back and re-wrote it to do it the right way. The act of documenting it revealed you left too much undone, or too many situations un-handled.
This is by far more common for me as well. I'll find myself describing some really brittle setup process or some common operation that seems to take a thousand steps, get embarrassed over how bad it is, and then go fix the code. More than once, I've written sophisticated automatic parameter selection code because it was easier than finishing the documentation I had started explaining to the user how to set up parameters properly.
Knuth (Score:5, Interesting)
Re:Indeed (Score:4, Interesting)
Write method.
Write unit tests.
Fix until it works.
Write documentation.
I generally find that code documentation is a lot better if the document first approach is used. In the above approach, the method is done, and the documentation becomes a chore.
This article from 1996 never gets old (Score:5, Interesting)
The term "documentation" is subjective (Score:5, Interesting)
There is an old joke: "The definition of promiscuous is somebody who has more sex than you do". From reading TFA and some of the comments on slashdot, I get the feeling that the definition of documentation is equally subjective and self-serving for developers. Some developers think that writing documentation means adding comments to code. Others feel it involves writing Javadoc/Doxygen-style comments at the start of every class and method, and then generating HTML from that. Yet others feel that documentation hasn't been written unless it involves an architectural description.
When I am working on my own open-source projects, I feel that documentation isn't complete until I have written a few hundred pages of text that aim to be cover most/all of the following: (1) API reference guide, (2) programming tutorial, (3) user guide, (4) architectural guide, and (5) suggestions for "future work" that I hope other people will volunteer to do. Yes, I recognise that I am a bit extreme in the amount of effort I put into writing documentation. However, it does enable me to elaborate on the thesis of TFA: attempting to write such a comprehensive amount of documentation often highlights not just coding bugs, but also architectural flaws. This causes me to work in an iterative manner. I implement a first draft version of the code. Then I start documenting it, and when I encounter a part of the software that is difficult to explain, I realise that I need to re-architect the code base a bit. So I do that, and then get back to writing documentation, which causes me to notice another difficult-to-explain issue with the code. Working in this manner is slow, and I suspect it wouldn't work in a business with time-to-market pressures, but I find it gives excellent results in my own, non-time-pressured open-source projects. I touched on this issue [config4star.org] in the documentation for one of my open-source projects.
Re:Common knowledge? (Score:5, Interesting)
If the code and documentation disagree, then they're both wrong
The documentation itself is probably not the important bit. The thing that a lot of programmers seem to do wrong is getting the correct ordering of the thinking and coding steps mixed up. Writing documentation first means that you have to do the thinking before the coding, and that eliminates a whole load of problems.
Re:Common knowledge? (Score:5, Interesting)
When I was involved in writing one of the first packet switching systems in Europe (AT&T, Belgium, 1979), we found a brilliant way to fix bugs was to explain the bug (and thus the operation of the program) to someone. They didn't have to do much, just nod and look interested. ... and the listener cold then leave.
Then usually about halfway though, the hapless coder (eg me) would go "Oh shit"
We called it the "tailors dummy" approach to debugging.
A bit like pair programming, only less labour intensive.