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);
as a bug finding tool. Lots of unhappy customers that way.
"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."
Not true.
Explaining your work is a great way to demonstrate that you actually understand it. As the article illustrates, perhaps the most critical part is going back and verifying that the code matches the explanation.
Insert self-referential sig here.
I have caught a number of problems documenting my code. When you describe what it is supposed to do and you realize that it really doesn't do that then you can correct as such. I would say I have found more incorrect behavior rather then show stopping bugs. However if we had shipped the product with the code the way it was we would have probably called it a bug so it is probably the same either way.
Procrastinating life a way at a rapid rate of speed.
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.
What TFA suggests is not new. But it astounds me how close this is to what Plato was saying 2500 years ago.
We use a commercial mail processing application.
The documentation stated that the feature works 'this' way.
Which was to route mail to and from third party applications.
It only partially did this, it wouldn't route it back from the application. Understand they they also integrate a optional licensed virus processing feature.
We contacted the company, and they said it worked 'that' way. 'That' way was far less usefull or functional.
We pointed to the documentation and they corrected the problem.
In my utopian world, the code is well documented and thought out. In the mutli-million dollar/SLOC world, it is a mountain dew/provigil fueled race to the finish line and payday. As schedule, cost and requirements slide in the middle of a project, the documentation is often left in the dust while we scramble to successfully compile our deliverable.
For debug, depending on the system requirements, the test software has even less documentation than the original software.
Please don't confuse documentation with actual planning. If you think documenting your code is helping to prevent bugs then you're most likely not doing your planning properly. There's a reason we do DFDs, function models and interaction, behaviour and structure diagrams. Use a better development methodology.
Writing documentation after writing the code shows that he doesn't exercise TDD, either.
The only reason you find bugs when writing documentation is because you are creating a duplicate set of logic in a different format which should match your source code logic. You would get the same exact result if you wrote the same application in another language, say C# for instance. It's amazing the bugs for find when you verify your logic in multiple formats.
FTFA:
public void doA(int num) {
for(int i = 0; i < array.length - 1; i++) {
array[i] = array[i+1];
}
array[array.length - 1] = num;
}
public float getB() {
float total = 0;
for(int num : array) {
total += num;
}
return total / array.length;
}
There's no excuse for copying array.length - 1 items on every update. Someone teach this guy about circular buffers, STAT. Then maybe he'll have something worthwhile to blog about.
His examples seem to be based on having documentation help poor design. Knowing what you feed to your methods is a basis for programming. If you can't trust that (external interface), be ready to catch the exceptions.
He also forgot the bit about testing; if you're writing stuff up without a design, try at least to write some testcases so that you can verify classes to work individually. Rather than piling them up like a card house..
If your code is good, it should be self documenting. Everyone knows what the variables 'foo' and 'bar' do.
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?
Plus he mentions concurrency and the confusion it may cause for other developers re-using the code, but doesn't address the obvious divide by zero that will occur if getB is called first even in a single-threaded application.
Peer reviewing all code before it goes into the main repository also does the same thing. And the upside is you don't need to waste any time writing documentation!
My life must just abnormally suck, I guess. I have no time for documentation. I barely have time to get code that mostly works done before I have to move on to some hot bugix, or I have to move on to deliver some feature the customer needs 2 weeks ago.
I always longingly read people talking about test driven development, or code contracts, or good code documentation. I mean I love all that shit. Sure would be nice if I could do it in the real world.
Either I have an extraordinarily shitty job or some people just have dream jobs where they have time to write this mystical "quality code" with documentation, tests, etc...
Either way, if you have time for that shit I fucking hate you.
This is why I got into the habit of not commenting code as I was writing it. I always saved the documentation as the last step before getting it ready for code reviews or committing it to version control. By documenting last you don't waste time writing documentation that may end up getting deleted because you decided on a different solution, doesn't get out of sync with what the code is actually doing, and it serves as a forced code review for yourself.
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!
"As an added benefit, documenting your code makes it possible for people who didn't write the program to use it."
Yes, this seems obvious, but it's not. It's a Zen koan. Really. It's a well-known fact that koans are more fun to write and think about than documentation.
Dance with the pinch pine blossom.
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 believe the opinion of the OP is that documentation forms a powerful technique for static code analysis. This I think is likely, although there are better tools such as peer review, and static code analysis tools.
I have to ask "at what moment in time did you write the documentation?". The purpose for the question is to point out that code changes across time. There are complex links between the documentation and code. These links are either correct, or in error. If they are in error we could categorise them as "bugs". True they are not bugs in the traditional sense: they are not the sort of bugs that can be detected and prevented with tests, or that affect the execution of the program, but they do affect the cognitive integrity of the code, and influence the developer.
Let us be charitable and assume that no bugs were present at the first release. Then changes are made. Fortunately for the developer, IDEs and refactoring tools exist that allow the developer to identity areas of the code that likely to be impacted. In a scenario in which code reviews are mandatory, other peoples intellect are present to help reduce the chance of consequential changes. The developers test suite is present to help prevent regression errors.
What about the documentation?
The links between the documentation and code are complex, and difficult to understand in their entirety: the nature of plain text is that facts are repeated all over the place. There is no automated way to check this integrity. Even in a world in which you review all the code and documentation, you have little or no tool support (unless you use a requirements management tool, which are expensive in developer time) to help you. Effectively you are adding a manual testing stage to each release.
So lets look at the costs:
In my experience documentation adds around 50% to the cost of coding. The release cycle time deteriorates, and code is released into the user community much slower, which results in a poorer quality product. More defects are introduced.
Lets look at the wins:
It is clear that the documentation for an API makes a massive difference to the usability of the API. I have yet to be convinced that documentation of the code enhances that maintainability of it. The OP is correct I feel in his assertion that documentation forces a peer review.
Personal conclusion:
Document your APIs as thoroughly as you can. Spend the effort you would have spent on documentation on more effective peer reviews, and more ruthless code committing practices that ensure that the code is more maintainable.
Most programmers complain about documenting because they've never been told the correct way to do it. Well here it is motherfuckers:
1) Requirements need to be written and have a unique id. Functional reqs = what is needed, non-functional = constraints on how things shall be done.
2) Design document = plan for fulfilling each functional req, each design configuration item has a unique id and references the id of the req it is fulfilling.
3) Architecture document = plan for fulfilling each non-functional req, each architecture item has a unique id and references the id of the req it is fulfilling.
4) In-code comments = id reference to the design/architecture/requirement configuration item the code is implementing.
Isn't this precisely what specifications written in formal logic was intended to solve? http://en.wikipedia.org/wiki/Formal_verification
Cool, the software we have to implement hardly has any documentation, so this must mean hardly any bugs ;-) Knew there had to be a reason why the documentation is hardly existing...
---
"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.
Everything else is nitpicking by incompetent people which do not belong in the audience anyway.
I'm sorry, you seem to have written incompetent people where you really meant to say,
Devs who need to make changes but who came on board after the original code was written;
Support techs who have to support and debug code they themselves didn't write;
QA folks who are responsible for making sure a release does what we claim it does before it gets out in the wild;
Managers who like to have some assurance that when they tick the little box labelled Task Complete , the task they've just signed off on is actually complete and correct;
Customers who are trying to understand why the software does [foo] when they expected it to do [bar];
Community members who'd like to contribute patches;
Tech writers who have to write end-user documentation.
Il n'y a pas de Planet B.
I found some bugs documenting my own code lately, but I think that only works if you write the documentation a month or so after you wrote the code.
Hey don't blame me, IANAB
Good code should require little low level documentation to describe it and of you spend your time writing tests surely they document the intent of your code and can be tested by a computer.
Personally I would prefer to see high level design drawings/sketches, tests and code I can read.
All in favor of the idea; but many boundary conditions are dependent on the implementation. If the documentation goes down that far into the implementation level - well ... it becomes code.
I was taught that in my first year CS studies, when we were required not only to write programs, but to clearly document the algorithms used. Are there really people that write software and do not know this? Well, I guess there must be. Supports my claim that the only real problem the human race has is too many idiots.
Most ACs are not even worth the keystrokes to insult them. Be generically insulted by this and ignored otherwise.
there are 10 types of people. those who read binary and those who don't.
why bother with documentation if you could read binary?
why bother with binary if you can read code that can be compiled to binary?
why bother with code if you can read documentation that can be compiled to code?
so why isn't there a code that is human readable and can be compiled to code? because its too damm hard for humans to do it. and if humans cannot compile code from documentation well, why would you invest in a process the yields no extra power, just extra place to introduce bugs?
documentation will not help, if it is not fused into the code.
you need to ponder before you go into coding? go talk to pinky.
If you can't think of a good reasonably short and descriptive name then you don't understand the concepts as well as you should.
I only use variable names like i,j,k for loops. I use x1,x2,y1,y2 and similar names only for numeric values. This is applicable when I am implanting math algorithms. If I have a lot of similar variables differing by their last digit and I'm not doing equations, I know I am writing code that I won't be able to read later.
I tend to declare one variable per line, and describe what I am using it for as a comment. If I have a lot of variables I split them into groups, which I separate by blank lines.
I try and avoid reusing intermediate variable names, unless they are in different lexical scopes. It is fine to have similar name inside loops that doing similar work, but make sure that you are not confusing concepts when reusing variable names thie way.
I have been working on algorithms, and have stopped and spent an hour or more thinking about what to call the variables. I do this when I get confused. It always pays off. When you have a good descriptive name and you see it in it's use context, you can actually see the mistakes before you make them.
Why is Snark Required?
No need to be sorry.
If you look closely you'll see that I have also written: Software using open standards for configuration and data uses open standards that have been documented already.
Devs can read that documentation.
Support techs can read that documentation.
QA folks can read that documentation.
Managers instruct Devs to change realities to resemble their incompetent believes.
Customers will never read documentation but, instead, contact/bother QA folks, Support and Devs.
Community members can read that documentation and contact Devs.
Tech writers write what they want (see Slashdot summaries).
Welcome to reality. Now mod it down as much as you want.
Reality? The reality is that a design document written before coding starts is likely to never be accurate enough to perform the kind of annotation you're talking about, because as soon as coders sit down with it to actually implement stuff, they'll realise the design missed some crucial point of logic about how the application should work. And as soon as the code is demonstrated to the customer, the customer will point out misunderstandings about the design. And as soon as you start changing requirements your entire cross-referencing scheme starts taking more time than actually implementing the software does. The developers begin to hate it. The managers start to hate the developers because they can't stick to an apparently simple scheme. QA wonders why the software that has been produced appears to be different to the software they expected to be testing (because the coders had to update the spec to fix logical ommissions, but nobody forwarded the revised spec to QA), and starts filing bugs against correct behaviour. Before long the entire system falls apart and people are bickering about whose fault it is.
Been there, done that, and it's the last time I ever work for an FTSE250-listed corporation.
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.
I'm currently writing up API documentation for a large code branch which was never properly documented (and wasn't written by me), but now needs merging into trunk. I've found several serious bugs in the code as a result, all from trying to explain to the client how to use the API. These bugs were actually blindingly obvious when the behaviour of the code had to be explained.
I've also found some horrible design issues, where various settings the code allowed were contradictory or meaningless, or one setting overrode the behaviour of another, unless something else had been configured, in which case... you get the idea. As soon as you try to explain it, the awkwardness makes the design problems incredibly obvious - and in fact a much better way of doing it is also obvious. I can almost picture the evolutionary process by which this code was written, with each developer adding a new feature without regard to how the whole thing hung together.
So documenting after the fact can definitely detect bugs and design weaknesses - although I don't think this is an ideal way of doing so. Having said that, I'm not sure forcing the developers to document their design beforehand would have helped either, as a lot of developers simply regard documentation as a necessary evil (assuming it is enforced), and will simply write down whatever it is they intend to code, no matter how awkward the result.
I guess you have to have a mentality which loves elegance at all levels, not just in the specific lines of code that are written but how the system as a whole functions. Unfortunately (and surprisingly to me), many developers don't seem to care about the bigger picture, even when they have a deep appreciation of clever or elegant code.
Sit around trying to make sense of the requirement
Write some code that they think does what the requester really meant
Spend most of their time fighting the code management system and getting it to build cleanly
Pull an all-nighter just before the deadline so it doesn't crash when fed correct input
Toss it "over the wall" to the integration team
Refuse to answer any questions about it as they're not "too busy" on the next project
Have a nice feeling of satisfaction that they never have to do support on old code, as none of it ever gets into a production system
Get promoted frequently for meeting their targets on productivity and delivery times
politicians are like babies' nappies: they should both be changed regularly and for the same reasons
Crap coders tend to focus on incidental things that they feel will improve the quality of their code, rather than addressing the issues directly.
When Argumentum ad Hominem falls short, try Argumentum ad Matrem
Attributed to Albert Einstein, the full quotation sometimes reads “If you can't explain it simply, you don't understand it well enough yourself". He was a smart dude.
The most useful type of documentation is about intent and goals: WHY does the software have these interfaces, what are they supposed to accomplish, what is the overall model of operation, etc. That, I think, is where the best bugs are found. If the model isn't complete, then the code won't be. And that kind of documentation isn't bulky or repetitive--it has a very high return on effort. It's also useful to have documentation that explains particularly clever or complicated implementations.
Less useful is documentation that can easily be inferred from the code. Writing API documentation by hand is tedious and unproductive. If the API and its parameters use well-chosen names there's not a lot to add--and using something like Doxygen makes it easy to include a few hints where they are needed. But Doxygen isn't the place to explain the architecture or system model--that should be thought out first, not stapled into API comments here and there.
Many times I've found bugs by explaining to someone how a system is supposed to work. Doesn't have to be someone who knows much about it, occasionally it's even been my dog. High-level documentation is just another way to exercise that technique, with the advantage that the explanation itself can be reused.
Debugging is about what the code actually does, and the hard part, why it does it.
The *right* kind of comments helps explain the "why" if the code is working right. I've been complimented for including comments that began "Maintenance note:" that explained non-obvious decisions.
But end-user documentation? You can generate test cases from it, but only a small fraction of those you need.
We use design by contract (google it) now at my company. Comments are part of the formal interface specification for our code.
You don't have formal interface specifications? Your code is buggy.
What this guy is talking about is a do-it-yourself code review; better would be to get coworkers to review it with you. It doesn't matter what technique you used to write the code in the first place, get a couple of fresh eyeballs to read and try to understand it.
As an unrelated comment, someone who thinks extra large gray on white fonts look good shouldn't be making web sites. At least he didn't put each paragraph on a separate page.
When I really struggle with a coding problem, I post it on Stackoverflow. Before I post it, I plan what I need to say.
I plan how to describe the problem, what I am trying to achieve and what I have done so far.More often than not, during that process of planning I find the answer to my problem and don't need to post anymore!!!
Sometimes you just need to take a few steps back, breathe and look at it from a different perspective.
Think about it, if I implement a feature that has absolutely no bugs, no problems, no one complained and it is all hunky dory all the way. How much praise will you get for it? How many of you have written in your annual self assessment, "I implemented a critical feature foo in 2009 that has no bugs reported on it"? If you had bothered to write something like that down, would it be given a higher reward than "I increased the speed of the feature foo by 10%"
A step further, if you had a choice of a complex, difficult to test algorithm (say, using AVL tree based on two custom hash functions on a data set) to give you a 10% speed up versus a clean simpler algorithm (say, using a std::multimap that is essentially a balanced binary tree) which one would be rewarded more by your company? If you had chosen the complex one and a critical bug shows up and the customer is breathing down the neck of the company, everyone from the VP of sales will be talking to you, asking when and how fast could you fix it, and if you do fix it, you get this glowing review and reward. The simpler algo? You are just leaving food on the table for some jerk to come in, replace it with a buggy 10% faster algorithm and ask for a raise, making you look like a fool implementing a "slow" algorithm.
The reward structure in the corporations place very little value on bug free code, reward it very little, under estimates the maintenance cost of buggy algorithms, the programmers see buggy/complex implementations as job security. That is the crux of the matter.
sed -e 's/Chuck Norris/Rajnikant/g' joke > fact
I've witnessed writing documentation / seudo lines of code in comments on what a section is suppose to do is a quick way to ensure all pieces come together; frequently able to leave those comments afterwards to describe the following 1-N lines below it.
On the flip side, writing documentation after code can indeed point out bugs if the code is scanned as the documentation is written; it's not unlike a form of Rubber Duck Debugging https://en.wikipedia.org/wiki/Rubber_duck_debugging .
In the end, the only glaring weakness is rewriting the (more minuet) documentation when refactoring the code it's describing. But I'd argue the extra time it takes to rewrite the documentation is, again, Rubber Duck Debugging the refactored code.... a good thing.
Documentation describes what you intent a piece of software to do. It doesn't assure that the documented piece really does that, but it can help catch design flaws if you realise that that's not the functionality you wanted.
The one I heard was try to explain it to a big cardboard cut out of a person. Halfway through you explaining it out loud to it you'll have a eureka moment even though you'd literally be explaining it to a big piece of paper.
Did you know 80 to 90% of the moderators on slashdot wouldn't recognize a troll even if one dragged them under a bridge.
software inspection -- you go thru and review the requirements and file bugs. fagan created this process a long long time ago. i've attended both fagan and tom glib training -- really got a lot out of tom gills training
I look to documentation as being my first blank-sheet synthetic user. Writing documentation early forces me to get out of developer mode and into user mode. If I can't write the documentation first, then I probably don't understand the problem space well enough to craft a usable solution. If I can't explain my approach to others, then I probably don't understand it well enough myself!
If you subscribe to the "Test Early, Test Often" mantra, then what can you test before you have written any code? Yup, the documentation. As soon as I feel I've documented something well enough enough to start coding, I release my documentation to anyone who wants to look at it. The feedback can reveal areas I missed or misunderstood before I have sunk too much time into building a wrong or incomplete thing.
As a developer of embedded real-time systems, early knowledge or perception gaps can become costly in terms of both money and schedule. Writing documentation and getting it reviewed will quickly highlight areas that need further examination or exploration. Where is more research needed? Which areas should be prototyped to ensure feasibility before choosing a specific solution path?
You can also view documentation as the first conceptual system test and last real-world system test: If the final product doesn't do what's promised in the documentattion, then either the worng product was built, or the documentation describes something that can't or shouldn't be built. Good to know this stuff ASAP!
Documentation is also a negotiation tool: It gives all stakeholders something to point at while describing their needs. It ensures we're all speaking the same language.
If you work in an Agile environment, negotiated documentation updates are one of the best ways to get needed changes into the product. This also means documentation is a living artifact: The code can't be wrapped up until the documentation stabilizes. It also helps bind distributed teams, again because it provides a common point of reference.
In a completely new project, the first document I write is the User Manual. It lets me distill requirements and use-cases into my conception of the final product. If my task is a library, then that document may fit in a README.txt file. If it is a device or system, it may be the size of a small book (depending on the size or complexity of the system).
When doing maintenance, the bug system is the primary gateway I use for deciding what should be changed, why it should be changed, and how it should be changed. The relevant bug reports and feature requests live only in text form, and evolve into stories that end with a "to do" list. Again, it's all documentation.
Finally, the code itself must also be documentation that can be understood by those who may need to maintain it later or re-use it in another product. When the code is working well and passes all tests, prior to release I host a code review. In addition to inviting other programmers, I always invite non-coders who have the technical acumen to understand the problems the software tries to solve: If the code and its comments are not self-documenting to a significant degree, then I have failed to make a maintainable product. Which means *I* may be stuck maintaining it, rather than being able to move on to new projects!
Documentation also has professional and ethical dimensions: My employer has commissioned and paid me to develop a product, and they deserve to recieve not only the final implementation, but also the means to maintain, re-use and re-engineer that product in the future. Anything that stays in my head becomes "lost" to my employer should I die or accept other employment.
My obsession with all levels of documentation came from a mentor whose code at a prior employer became an issue in a law suit between his prior employer and one of their competitors. Because he was working at a third competitor, his then-current employer was able to prevent him from testifying, arguing that his prior code con
Not code documentation, but end user documentation was my gig for a while. At one point there were more Bugzilla entries from me (entered as I tried to use and document the software) than from the whole 15 person QA team put together. It was one of the experiences that drove me into software testing and then pen testing.
More on topic for the article, my current employer implements extensive unit testing before any code is written (no really, I know lots of places say they do this, but it actually happens and is useful). Specifications are written by non-technical people and then tested and approved by those people before code is accepted. It also goes through a technical review and blackbox testing before acceptance. I'm not sure writing technical documentation would add a lot to the process, but I'd like to give it a shot and see how the experiment plays out. I'll bring it up next week and see if the team has any interest.
Several commentators have said that reviews are better than comments, but this is no argument against commenting, as they are complementary and synergistic activities. I have found in practice that reviews without prior documentation are almost worthless, and generally not cost-effective.
1) Having the author write down an explanation of her code saves the time of half a dozen reviewers trying to figure it out. This, alone, is justification enough for pre-review documenting.
2) The alternative, having the author try to improvise an explanation in a review meeting, and have the reviewers follow along, leads to incorrect assumptions going overlooked or unchallenged, and may degenerate into confusion.
3) As others have pointed out, the author is likely to find some errors as a result of documenting the reasoning behind her work, leading to fewer failed reviews, and consequently, fewer repeats.
4) If the reviewers don't fully understand the whys and what-ifs of the code being reviewed, the exercise degenerates into a search for coding standards violations.
5) Comments, if both relevant and correct, save a lot of time in future whenever that code needs to be understood. While this is not the most important case where this matters, it includes when reviewing changes to that code, and any other work where its correctness is conditional on the prior code. Having the commented code and other documentation being part of reviews helps meet the relevant and correct criteria.
iff you document what a function *should* do, you *can* compare its projected behaviour to that.
python doctest ftw! - http://docs.python.org/py3k/library/doctest.html
On a long enough timeline, the survival rate for everyone drops to zero.
I call it a "test plan".
1. Write test plan
2. Hand it to developers for review
3. Developers read test plan
4. Developers consider factors, conditions and workflows spelled out in test cases that they hadn't thought of before, because they are developers not QA engineers (if a developer were capable of doing what I do, they would never have written into code the bugs that I find. Developers are not, and never will be, superior to QA engineers. Life lesson, prima donnas: QA saves you from yourselves.)
5. Developers examine their code with these new insights
6. Developers fix bugs in the code, prompted by the document (test plan)
I realize this all breaks down at step 3, but I can dream.
Everybody gets what the majority deserves.
In my day we called this "Requirements". we wrote them before we wrote code, and we tested the code to make sure all the requirements were met.
Ken
I always thought this was just a joke: http://www.sjbaker.org/humor/cardboard_dog.html
Can a person program a new solution to a problem? Why should anyone be able to stop such a thing? -Richard Stallman
Any programmer/analyst is capable of what you do which amazes me your title even exists at all. Same with most IT/IS/MIS "managers" who haven't written a line of code in their lives. Too much of that crap has gone on for decades.
You know - the other account you use here to troll others with also?
barbara.hudson@barbara-hudson.com from http://slashdot.org/~tomhudson shows Barbara/Tom could pull off just what you've noted by keeping 2 registered accounts here. Spare mod points to downmod his/her detractors with and to upmod herself too.
http://slashdot.org/comments.pl?sid=2787367&threshold=-1&commentsort=0&mode=thread&pid=39697575
http://slashdot.org/comments.pl?sid=2787367&threshold=-1&commentsort=0&mode=thread&pid=39697575
http://slashdot.org/comments.pl?sid=2787367&threshold=-1&commentsort=0&mode=thread&pid=39697575
When I write little utility programs, I start by writing the words that will come out with "--help".
That's good for little util progs, but for larger progs like 'bash' or 'vim', --help just doesn't cut it...
Then there's issues about what is a bug and what is not. I've seen that used percolate down from committee's as well. Where incompatible changes are introduced, by say, POSIX, -- but that's ok, because, it's in the POSIX spec! (the latest rev of it, that is...)..
Documentation can be used as a spec -- or it can be used to document bugs or inconsistent changes as a means of supporting the change.
As a former network manager (most of who's job was supporting various special purpose software products) I can tell you that I got sick to death of supporting software where it was obvious that design decisions were based on what the programmer knew he could do easily. Sure, you wrote a program that could do "D" but my users had to go through "W" then "L" and then "R" to get there. Oh, it all made perfect sense from a programming perspective. I could easily see why a programmer would add that feature in that particular manner. But it made even educated users feel like idiots trying to figure out the logic of how they were supposed to do things. I have overheard minor religions being invented while users try to figure out why in the world they have to go through "W" then "L" and then "R" to just get to "D" when they are sitting at "C" right now. It was so bad that it is the major contributing factor for my decision to get out of the IT field. I got sick and tired of trying to make software just simply do what the vendor said it would do.
So, I am a firm believer in writing the USER documentation before writing a single line of code. If you can't explain how a user is supposed to get from "C" to "D" in a simple, coherent, manner which is somewhat consistent with how they got from "B" to "C" then you aren't finished designing your program yet. Have your grandmother read the manual. If it doesn't make sense to her then you got more work to do. Sure, your code may be elegant, with clojures and functional programming all over the place. Your class structure may be the envy of all who maintain it. Sure you may be able to refactor the holy hell out of it and every bit of the code is reused three times. But if users can't use it then what the F is the point?