Clarity Is King…
The importance of ensuring clarity in written work isn’t all that controversial. The general reason is simple: the total amount of time everyone spends reading something is typically much greater than the amount of time it took one person or one team to write it.
The controversy alluded to is in the bucking of several bad habits that have very large followings. These bad habits fly in the face of clarity, and unfortunately they don’t receive the appropriate level of scrutiny.
The first bad habit is a bizarre programming style where curly braces are placed on lines occupied by other text. This is a holdover from antiquity when screen monitors were tiny and every pixel was highly coveted. In that age, you could have made a case for sacrificing clarity in order to have a few more rows of code on the screen at once. These days it is inexcusable, and when you have to read this stuff, sometimes it can seem almost unforgivable. With the prevalence of huge monitors, multiple-monitor setups, and futuristic code editing tools, why would you make your code harder to read in order to save a few pixels? Screen space is cheap.
The main difference between the left and the right example above is symmetry. Things that are symmetrical are easier to read. They’re easier on the eyes. Also, on the right, things are more structured and orderly in that the curly braces are on their own lines and so you don’t have to read around them as if they’re clutter. And so, all of that is simply to say, the style on the right is objectively better. Now, if you don’t program and don’t know whether to believe me, try reading the next two fragments and decide for yourself which is better.
I’m not aware of any other engineering discipline which creates documents or artifacts that regularly sacrifice clarity in this manner.
Two other questionable habits involve constructs in the English language: the Oxford comma, and sentence spacing. In both cases, the method that promotes the most clarity ought to be chosen, but yet many people opt for the alternative. I claim we ought to put two spaces between sentences, and we ought to use that final comma when listing things (except in rare cases where it actually introduces ambiguity).
I really believe the Oxford comma speaks for itself.
And if there’s any doubt about leaving two spaces between sentences, just consider how many spaces we put between paragraphs, and then think about the reason behind that. If an author merely wanted to express a change in something, such as a new speaker, this could theoretically be done without jumping to a brand new line. For example, a hyphen prefixing the next sentence could indicate this change, and that would be much more economical in terms of space. Of course, we all know which method is used to indicate a new paragraph, and I believe the reason it’s been around for so long is because readers perceive change more easily with the help of additional white space. This type of visual aid is as applicable to sentences as it is to paragraphs.
Although the two English language examples sacrifice much less clarity than the programming example, all three are valid subjects for inspection. In general, why not adopt the approach which promotes the most clarity, especially if the cost is negligible? The cost of not doing so for any one piece of work is nominal, but in the aggregate, the cost is much larger.
