5 ms·
I completely disagree. When code changes rapidly, and especially when multiple people are working on the same code, documentation which explains the "why" of t
by kscaldef 16y ago
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.
- christoph 16y agoIt might be worth it, but the best code I ever wrote had 0 comments, it didn't need it...
- nostrademons 16y ago"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 16y agoI 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 16y agoI 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 16y agoThe 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 16y agoWell put. The same goes for comments, too. Someone else asserted that good comments should reflect "Why" more than "What". "What" changes more.