Almost all of the time I agree. But sometimes code is the clearest and most understandable way to describe an algorithm, and sometimes you want to describe an algorithm for a reason other than that you want it to execute. For example, you might want to say "This would be simpler but it fails when x is denormalized," or you might want to say "This is how you could call this method," which is common in Python and elisp docstrings — and, I think, wholly defensible in that case.

Most days I don't write comments. Maybe once every 3 months. When I feel like someone might need a comment I rewrite the code until I feel like they don't need a comment.

The only time I write comments is when:

1. Someone fucked up big and shipped an iPad app or something that relies on an error in the API or something. Can't force users to upgrade iPad apps, especially on older ones who are fearful of the app breaking or getting worse, so you end up with these massive comments fully explaining the problem, the hack that solves it, the conditions that need to be met in order for the hack to be solved (for example, "check google analytics to see if the number of people using version X of the iPad app or lower is less than 1%, if it is, replace the bellow hack with the following solution"), and possibly other hacks investigated and the reasons that they were declined. The reason you do this in the code rather than just in the commit message is that it protects the message from getting watered down as people change the code. I assume that someone is in a massive hurry when they are reading code and massive wtfs should be explained without further investigation.

2. When the performance of the obvious solution is terrible and the efficient solution is complex. Especially when math is involved (for example, the core match method of a distributed recommendation engine).

In cases where something is fundamentally broken but something "needs" to be changed now, I do this.

i.e:

// This is how it should be // foo(...) // But, since the code is horribly broken, we'll have to do: bar()

This is a neat trick, the best I've seen for commenting out huge blocks. But yeah, there is no reason for commented out code.

From "97 Things Every Programmer Should Know" http://programmer.97things.oreilly.com/wiki/index.php/Commen...

> Commented-out code is not executable code, so it has no useful effect for either reader or runtime. It also becomes stale very quickly. Version-related comments and commented-out code try to address questions of versioning and history. These questions have already been answered (far more effectively) by version control tools.

>a) delete the code. It'll be in version control anyway right? You do do version control right?

If only digging code up from a previous version was as easy as uncommenting it.