Comments and self-documenting code are like brandy and cigars, the first illuminating your source (meaning both the gentleman’s soul and the source code into which he pours it), and the second imparting a blazing instance of clarity where you can taste the meaning.

Adherents debating the styles travel parallel roads in the direction of improving maintainability, but take opposing paths (and tend to toss aspersions across the median). Comments depart from reality over time and are perhaps redundant by nature, while self-documenting code is a frequent vanity and incapable of reflecting the many levels of abstraction that constitute design. I think a good way of realistically traveling these issues is by practice, and naming your branch conditionals (the subject I raise this very moment!) is a modest but noble idiom suitable for any lounge in solitude or with a cordial in hand.

Branch conditionals are important thing to name right because they’re all but the core flow of your code and you’ll be reading them over and over again in the repetitive quest for understanding, and its more senile relative, recollection. Branch conditionals (usually) look like this:

If (x && (y = (d  ? a : b) || y < e.p() ) )
{
blah();
}
else if (t.F() && g == q[0])
{
meh();
}

A far more readable and self-documenting way to formulate the code would simply be:

var isThisThingAndAlsoSomethingElse = (y = (d  ? a : b) || y < e.p() );
var butThatCouldAlsoBe = t.F() && g == q[0];
If (isThisThingAndAlsoSomethingElse )
{
doThis();
}
else if (butThatCouldAlsoBe)
{
doThat();
}

I find the separation of the comparisons from their consequences to save hundreds of milimoments of thought when working with code. Like most advice, it’s quite simple, and nobody follows it. The highest value can come from small optimizations like this, and collectively, when I scroll through source code with a lot of named booleans I read it that much faster than short files with pithy dents of anonymous conditionals.

In fact, I find this simple idiom useful enough that if I were granted one wish about all the code I’m to read before I die, well, named branches would be the second after the simple demand for thoughtful, verbose variable names, of which named branches is a like subset to begin with so it’s reasonable several times over.

A fortunate byproduct this practice is that naming branch conditionals can sometimes be hard, a fact you should use as a chance to articulate your logic. Choosing a name can also be a useful secondary measure of code smell, or suggest method refactoring, or reveal problems with business logic, and what’s more it’s a further refinement in this world of programming where nouns and verbs are given descriptive titles yet filled with murky details.

So what you have is self-documenting code because it reads like a comment, and it must read like a comment in order to express a more or less complex branch conditional. At a higher level, idioms like this are showing up in a lot of other places like Domain-Specific Languages and advice on naming tests, which are arguably just a branch conditional at heart themselves. What that suggests to me is that it’s a useful detail for programmers to orientate to.

Benefits: readability; passive analytical tool; DRY.
Costs: verbose; antagonizes our instinct for quick and clever over clear.