I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than try to squeeze it in to a few camel-case words if that would compromise the clarity.

It's much easier to fool yourself into thinking you're writing "self-documenting code" if your "documentation" is just a natural language rephrasing of your code.

When your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g.,

double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_meter, double moment_of_inertia_in_kilogram_meters_meters);

vs

// Units are base unitsSI.

double compute_angular_accel(double tau, double J);

I'll take the second any day.

What about the day the Mars climate orbiter was lost because one piece of code wrongly assumed that the units of figures out of the other piece of code? :)

I find that you do sometimes need symbol names that long even though it's a code smell indicating something else is up - usually scopes that are too large or insufficiently expressive types.

I view excessively long variable names as a midpoint on a journey to improving code quality on really bad code bases.

While what you say about long variable names can be right in certain circumstances, the example with the wrong units is inappropriate.

In my opinion any code that deals with physical quantities, but which does not use dedicated types for each kind of physical quantity, where the type definitions include the units used, is erroneous.

Any mistake like in the Mars orbiter must be detected at compile time.

It's also substantially easier to update a comment, making it more descriptive, than it is to update a variable name.

The funny thing is, when someone writes really 'clever' code, I need a why more than ever. Why isn't this simpler?

I find the exceptions usually boil down to:

* It's not your code - I was working with some UNIX TTY code recently and the APIs are horrendous 1970s throwbacks. But they're not changing. Working with crappy APIs is where comments about the "what" shine the most. You can only go so far with abstraction/encapsulation/facades.

* You don't have time - there's an urgent bugfix you need to get out yesterday. Do you A) rewrite the architecture to make it perfectly understandable and tell the users to wait B) drop a comment in explaining what's going on.

> And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever.

Yep, that'll happen, and when it does, you document why you documented the 'what'! :P

This kind of lazy black-and-white thinking is what 'consistency is the hobgoblin of small minds' is talking about. The exception proves the rule (...most of the time...)