[nostrademons]

Otherwise known as Literate Programming with an IDE. :-)

The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader things that are wrong.

It works great for TeX, not so well for a startup that will have a new business plan in a couple months. That's also why the best comments tend to be API docs: APIs change (or should change) much less rapidly than implementation, so the documentation is both more useful and has less chance of being out-of-date.

[kscaldef]

I completely disagree. When code changes rapidly, and especially when multiple people are working on the same code, documentation which explains the "why" of the code is very valuable. Without it, you're left trying to figure out if some piece of code is really necessary, or still necessary. If you're lucky you can rum 'blame' and figure out who wrote the bit in question and go talk with them about it. If you're unlucky, they don't work there any more. Either way, it's more time consuming that reading a good code comment about why something is being done.

Is there a cost to writing good comments? Yes. Does it take discipline to keep them up-to-date and accurate? Yes. Is it worth it? Yes.

[nostrademons]

"Why" comments are often quite useful, but the example in the article was filled with "What" comments, and doesn't seem to be talking about that at all. "Why" comments are often infrequent enough that there's nothing wrong with putting them inline with the code.

[shahriarhaque]

I agree that "Why" comments are infrequent, but they are still important. I work in the scientific computing field and here "whys" are they key to understanding code. But lengthy explanations of why certain steps of the algorithm are needed, are very distracting. Such a scenario calls for a separation of code from comments.

[Xurinos]

I agree with this response. This is the same argument as for unit testing. When your code changes, you have to maintain your tests, too, sometimes throwing them out with the deleted code.

In other words, for any code change, you could have a test and a comment. And that is part of the job. The job is not just "write code". It is "write maintainable, bug free code".

[nostrademons]

The point of unit tests is to provide an executable specification. Ideally, the specification changes less frequently than the code does. In practice, the specification tends to change a lot too, but you should be able to perform optimizations or refactorings without having to change a whole lot of unit tests.

I know teams that have an "every change should break some unit test" policy, and IMNSHO those teams are making way more work for themselves than they need to. The point of tests is not to make sure that the code does what it does, the point is to make sure that it does what you need it to.

[Xurinos]

Well put. The same goes for comments, too. Someone else asserted that good comments should reflect "Why" more than "What". "What" changes more.

[christoph]

It might be worth it, but the best code I ever wrote had 0 comments, it didn't need it...