The assertion that comments are a code smell assumes that the source of complexity in your codebase is either developer taste or some computer-sciency problem that becomes apparent to anyone reading the code in a few minutes or so. But sometimes the complexity is intrinsic to the problem you're solving; sometimes there's some quirk or edge case that means you can't do the obvious thing. In those circumstances, you need comments to explain what you're doing, how you're doing it, and why.
The code tells what the program actually does.<p>The comments tell what the program <i>should</i> do.<p>This distinction is so important that English marks it syntactically. Here's an example of how this shakes out:<p>BAD: // this routine takes its input, multiplies it by 9/5, and then adds 32<p>Good // this routine converts Celsius to Fahrenheit<p>Another example: is this code buggy? for(i=0;i<=10;i++) { // do something }<p>No way to know if you don't know the programmer's intensions, which is to say, if you don't know what the code <i>should</i> do.
<i>> Well, I dunno. I think the smell was there before you wrote the comments. The comments are febreze.</i><p>Awesome! I will never look at comments the same again!
I use a lot of comments during development, but rarely keep them around in final production code. As features become stable, I tend to subconsciously delete them in the underlying areas.<p>My rationalization is that source control has already captured this history, and if someone really wanted to see what I was thinking, they could review the commit(s) for that file and get a perfect picture.<p>There are some places where I think comments should persist, such as where you expect future developers (yourself) will be breaking ground again for additional features. Things like "TODO: New Components go here" on a switch statement, or "Review the following issue # for change process around this type" located at the top of a very important piece of code.
I'm not really sure what the takeaway is here. It's not "don't write comments" since that would not have helped the situation.<p>At the very least, if you're going to write comments, bug reports, and code reviews, each one should be descriptive enough _on its own_. Not the right time for DRY! It is indeed irritating having to follow a thread across several places to get to the answer.