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."
Common knowledge? (Score:5, Insightful)
Re:Common knowledge? (Score:5, Insightful)
I thought everyone knew that documentation describes what you intended code to do, rather than what it actually does.
The documentation tries to document what your intentions are, just like the code tries to implement them. The code can fail to do its job, and of course the documentation can too!
IS0 9000? (Score:5, Insightful)
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.
Re:Common knowledge? (Score:5, Insightful)
I thought everyone knew that documentation describes what you intended code to do, rather than what it actually does.
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.
Any time your documentation reads like you are describing a game of twister [wikipedia.org] you just know the code can't be worth documenting, or even keeping.
But as for finding bugs, I don't know. You may document exactly what you intended, and thought the code did, but still be wrong because of some corner case. Documenting it isn't likely to reveal all of these situations any better than the code itself. A
Re:Common knowledge? (Score:5, Insightful)
Re:False (Score:5, Insightful)
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.
Re:Common knowledge? (Score:2, Insightful)
Tell that to the PHB that wants the code to ship YESTERDAY--bugs or no bugs!
To me, proper programming is and exercise in minimalism--get the most work you can out of the simplest and least least amount of code.
Then comments/documentation isn't so critical.
But that takes too long and time is money to the average PHB. So you get apps that barely work and must be 'updated' to work better and to be an income stream for the company that put said software out.
But when you have people DELIBERATELY writing needless, convoluted code in an effort to keep their job because they are the only one who can upgrade it--you have the situation we have to day which is addressed humorously by the The International Obfuscated C Code Contest [ioccc.org]
Documemtation Priority (Score:5, Insightful)
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.
Re:Common knowledge? (Score:4, Insightful)
If you really filled 30 positions in 2 months, your problem is likely in hiring shitty programmers. A most companies I've worked at, we made offers to 10-20% of the people who interviewed. Unless you're doing 5+ candidates a day, and all offers are accepting, you're murdering that rate. Some of that may be better offers or more efficiency, but it sounds like you're hiring a lot of mediocre people to fill seats.
Theory doesn't always work in practice. (Score:5, Insightful)
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.
Re:Theory doesn't always work in practice. (Score:5, Insightful)
You need to distinguish between functional and technical specs.
Functional specs are very usefull (if done even halfway right). Technical specs are a waste of time unless you assume by default that you're dealing with incompetents, in which case you're better off saving yourself time, money and aggravation and hire a better developer.
So I do write a lot of functional specs. Even now, in an agile environment, with HUGE time pressure and multi-million penalties for delivering late - just finishing up my final 40 pages (90 pages total, in this 4 week sprint). Why? Because not doing so will make the project much later. Good architecture (system design) specs will make the project about 20% more likely to deliver on time (citation if I can find it again) even if the programmers don't follow the guidelines (interesting, right?). This matches with my experience: if you write decent designs, you are more likely to find the pitfalls before they can bite you in the ass. If you cover all the bases and make sure the business has provided for all scenarios before you get there, your project will run smoother.
So docs may not prevent all the bugs. But it does prevent a large number of nasty stuff before it gets to the stage where it turns into a defect.
Re:Common knowledge? (Score:4, Insightful)
So let's get this straight: you just sacked 60% of your developers for not following certain rules?
That 60% of your developers had properly been informed that certain rules were important enough to follow that breaking them would probably mean dismissal, and then went ahead and broke them anyway?
That there was no process in place of informal verbal warnings / formal verbal warnings / formal written warnings that could have been followed before sackings?
That this wasn't discovered before it was widespread enough that it became necessary to sack 60% of your developers?
That you have decided you'll be more productive in future with only 40% of your new development workforce having any experience of your software whatsoever?
Your company has BIG problems.