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.
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.
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!
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.