Slashdot Mirror
Documentation As a Bug-Finding Tool
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."
I thought everyone knew that documentation describes what you intended code to do, rather than what it actually does.
while(1) attack(People.Sandy);
Say what you do.
Do what you say.
The documentation becomes an error check on the code and vice-versa. If the 2 disagree, something needs to be fixed.
Explaining your work is a great way to demonstrate that you actually understand it.
My standard development process is:
My rationale is precisely that: I'm not really sure I know what I'm doing until I've described it, then figured out how my idea might fail.
Forgive my ignorance, but doesn't everyone do this?
Crumb's Corollary: Never bring a knife to a bun fight.
For some methods of documentation this is very true. For some programmers that care about their work its very true.
But if you don't care about your code, you probably won't care about the documentation. In this case, I agree its False.
If you know the documentation you just wrote is a bag of lies but you turn it in anyway, because you know that the PHB won't understand it and couldn't check if it was true if his life depended on it, then you might as well junk the code you just wrote as well. Chance are it will break the minute you walk out the door.
Sig Battery depleted. Reverting to safe mode.
Oh, come on, Literate Programming has been around for 30 years! Knuth made exactly this argument in his 1984 essay entitled, surprisingly enough, "Literate Programming!" Wikipedia asserts in it "Literate Programming" entry: "According to Knuth, literate programming provides for higher-quality programs, since it forces programmers to explicitly state the thoughts behind the program, making poorly thought-out design decisions more obvious. Knuth also claims that literate programming provides a first-rate documentation system, which is not an add-on, but is grown naturally in the process of exposition of one's thoughts during a program creation. The resulting documentation allows authors to restart their own thought processes at any later time, and allows other programmers to understand the construction of the program more easily."
Congratulations to Slashdot for posting about some kid rediscovering an ancient technology by a revered master of the craft. What's next? "Snot-nosed highschooler discovers GOTO is a bad idea?"
If you're so smart, why aren't you naked?
Manager, at the beginning of a project: "Forget the documentation! Just get it to run!"
Manager, at the end of a project: "Where's the documentation! You were lazy, and didn't write any!"
Documentation is at the ass-end of a project. The Manager's Manager wants to see something running. He doesn't accept paper as a currency. So documentation will always get low priority. And that ass-end will be hanging out and swinging in the breeze.
Someone could do a scientific study that proves that documentation cures cancer.
It will still get low priority in a software development project.
Schroedinger's Brexit: The UK is both in and out of the EU at the same time!
I believe this is the method Knuth recommended, and formed the beginnings of the idea of literate programming.
"First they came for the slanderers and i said nothing."
I think most people to this:
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.
"God, root, what is difference?" - Pitr, userfriendly
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 in the documentation for one of my open-source projects.
The theory was, write the documentation, then code to the documentation.
In practice, that isn't sufficient to reduce bugs significantly, for several reasons.
1. As you develop something, you find that "getting from A to B" sometimes requires going via D instead of C;
2. Other times, you realize that the documentation doesn't completely capture the requirements, and you need to visit both C and D, and maybe Z
3. Still other times, you realize that A is entirely superfluous.
4. "Can you add/change this feature?"
The initial specification should never be too specific about implementation details - that's a mistake that too many people fall for, going with the illusion that they actually can nail down every detail of a non-trivial problem and just throw the spec at "code monkeys." They don't understand that a specification should only say what, not how. Writing "code documentation" before writing the code is writing the "how".
So they can end up with something that meets that spec, but doesn't work either as intended or just flat-out is wrong.
Unfortunately, code, then document (when and if you get around to it) is the reality because, unlike theory, reality is messy.
Let's call it what it is, Anti-Social Media.