Good Writing, Code and Otherwise
A quick web search reveals numerous articles that describe how programming is like writing. Some of these articles talk about how your paragraphs should be concise and do one thing, as should your methods. And how good languages — computer or human — let you to organize and express statements in numerous ways, which supports composing paragraphs or functions with maximal clarity. Some talk about how good writing is formatted so that it is visually accessible. And some articles talk about omitting unnecessary words.
Most of these articles omit or gloss over a critical point about good writing: You should never ship a first draft. Writing, whether the end product involves code or words, demands continual editing. Professionally-written expository books and articles don’t make it to publication without editing to ensure that the writing is clear and concise.
The most important outcome of a program is that its code must command a computer to act in a certain way — but that’s not sufficient. It’s possible to write code that issues all the correct commands to the computer but demands extraordinary effort from people trying to read it. So, in addition to the significant challenge of writing correct code, you need to ensure it makes sense to others.
Good code is readily understandable by other humans. It doesn’t slow down someone who must understand and maintain it. A well-written function might clearly impart its meaning in 20 seconds or fewer. A poorly-written function might require a few minutes, perhaps more—an order of magnitude longer — to comprehend. Worse, this cost increase gets incurred by everyone who must read that function from here to the near-eternity of that code’s existence.
Much of your programming day likely involves changing or enhancing existing code. Doing so effectively requires you to first understand the relevant existing code. If most of that code is poorly written, a large proportion of hours in your programming day becomes wasted time.
Good Code Doesn’t Just Happen
Good code doesn’t magically appear on the page. Despite good intent, virtually no one spews perfect sentences out of their mind directly onto paper on the first try.
Good expository writers edit their sentences as they go. They first splash words onto the page, to quickly capture their current thoughts about the idea they’re trying to impart. They then revisit the new, fresh text to correct grammar, clarity, conciseness, organization, and other problems.
During their editing process, writers replace some words with better ones and reorder others. They shorten sentences to get directly to the point. Organization is important: Writers also move sentences about, attempting to create consistent structure and provide a sensible flow — from one thought to the next, one concept to the next.
Not-so-good writers splash words onto the page and quickly move onto the next idea. Rather than edit their text, they leave behind a mire of prose that confuses, irritates, and ultimately fails at its goal of informing the reader.
Not-so-good code writers are no different: They splash code onto the page and move on. Their functions get longer, as do their classes, ending up as collections of haphazard statements with convoluted logic. Determining the intent of such code requires careful, step-wise reading and mental calisthenics.
To be a good programmer, you must edit your code, like a good writer edits their words. Yet the majority of programmers do little more than a cursory pass at editing. Why? Because it’s hard enough getting the code to execute correctly, and further editing only invites opportunities for breaking things that were already working.
We — both writers and programmers, all human — make mistakes all the time. Mistakes in words run the risk of misinterpretation, but one simple mistake in code is all it takes to render software worthless or worse.
Some brave folks happily edit their code without proper safeguards, but it is slow-going and risky. Some of us use appropriate test controls and continually edit our code, as good writers should. We fix the code, even if it ain’t broke — because it’s a critical part of good writing.
