Two Types Of Code Clarity

There are at least two types of code clarity.

You get one form of clarity from medium-sized, well commented methods, that tell the when, why, and how of the code, and are easily followed because algorithms and logic flow are all together in one or just a few methods.

Another clarity emerges after you RefactorMercilessly. Methods are short, with IntentionRevealingSelectors? replacing comments. Redundant code is removed. You look at small pieces of bare-bones working code itself, and the code tells you what it is doing.

This may be stretching the metaphor a bit, but the first type of clarity seems like the clarity of a text book or a tutorial, while the second type of clarity seems like the clarity of a reference handbook.

A text book or tutorial provides context and explanations. It is easy to read. It is a fast way to get up to speed. A reference handbook doesn't claim to teach you - but it is good place to look up small, specific things. It is a fast way to learn once you are up to speed.

Neither one can be claimed to be clearer - it depends on your needs.

Yes, clearly it depends on your needs. Fortunately we already know our needs. We need code that is easy to read and understand and at the same time easy to maintain. Under these conditions we find that a single well documented method takes twice as long for this activity. First we read the comments, then we read the code, and then we figure out how the code implements the comment. Now we change the code, and then we change the comments. A well factored comment-less set of methods requires us to read the code and change the code. --DonWells

That's fine as far as it goes, Don, but to me it misses one of the main points of the initial assertion. The dichotomy is not really between commenting and non-commenting, but between grouping code to express recognisable chunks of domain functionality, and code produced using RefactorMercilessly and OnceAndOnlyOnce. To me it's a similar issue to that which I raised in ExtremeNormalFormDefined; at what 'granularity' of code do you stop refactoring.

I tend to think that code which has been refactored too far turns into RavioliCode, where almost any maintenance change can be achieved in only one place, but it can take ages to find which place. --FrankCarver

There is an art to seeing/writing radically modular program structure in the Smalltalk browser. The uninitiated, for example, often complain that such programs have no beginning; no right place to start reading. Those writing in the style are rewarded with startling flexibility. This comes in part from the whole-method overriding semantics of inheritance. But equally important is the dicipline of naming every step and making every step deserving of a name. -- WardCunningham