This post was originally written while I was at LShift / Oliver Wyman
To continue the analogy, students of creative writing have access to a wealth of training e.g.: courses, books and videos, writers’ circles etc. Similarly for programming there are: reams of open source code hosted on public servers, peer review and feedback through pull requests, discussions on aesthetics and elegance , and so on.
Using the musician analogy it may be tempting by some to regard a Lead Developer as a kind of orchestra conductor, but I’m more attracted by the analogy to a literary editor (or cat-herder, which may be the same thing “I love deadlines. I love the whooshing noise they make as they go by”) not least when it comes to the issue of Coding Style. For example, in my opinion, the best book on code style ever written is Perl Best Practices by Damian Conway – not because of perl as such (superb in its day, but it’s time to let it go for all but the simplest text munging) but for these 3 paragraphs on page 6:
Other readers may object to “trivial” code layout recommendations appearing so early in the book. But if you’ve ever had to write code as part of a group, you’ll know that layout is where most of the arguments start. Code layout is the medium in which all other coding practices are practised, so the sooner everyone can admit that code layout is trivial, set aside their “religious” convictions, and agree on a coherent coding style, the sooner your team can start getting useful work done.
But remember that each of piece of advice is a guideline … Whether or not you agree with all of them doesn’t matter. What matters is that you become aware of the coding issues these guidelines address, think through the arguments made in their favour, assess the benefits and costs of changing your current practices, and then consciously decide whether to adopt the solutions offered here.
Then consider whether they will work for everyone else on your project as well. Coding is (usually) a collaborative effort; developing and adopting a team coding style is too.
[my emphasis] and it’s often useful to pick an off-the-shelf style and stick with it (for a project) rather than agonise about tiny optimisations.
So can we perhaps look further to literary practice to guide us in software development? Well, here’s part of Gwynne’s introduction to Strunk’s “The Elements of Style”:
Remember always, when you are writing for anyone other than yourself, that you are giving. Do not, therefore, write to suit yourself: write with your readers constantly at the forefront of your mind. Put yourself in their shoes when you are deciding how to express yourself. It is not enough that you yourself can easily understand what you are writing down; you are not writing for yourself. Will they understand it? Can you make what you have just written clearer, so that there is no possible excuse for their misunderstanding it, or even for their having to pause over it for a second or two in order to see its meaning?
And a key paragraph from Strunk’s guide itself (NB. this was written in 1918, so I apologise for the jarring gender bias):
It is an old observation that the best writers sometimes disregard the rules of rhetoric. When they do so, however, the readers will usually find in the sentence some compensating merit, attained at the cost of the violation. Unless he [the student of English writing] is certain of doing as well, he will probably do best to follow the rules. After he has learnt, by their [tutor’s] guidance, to write plain English adequate for everyday use, let him look, for the secrets of style, to the study of the masters of literature.
I don’t think the similarity of the sentiment in these three pieces is a coincidence. Quite simply I hold the opinion that programming should be the act of communicating clearly to another programmer (it’s a useful coincidence that the computer can also understand what’s desired and even prove it in some circumstances).
This is a notion I was trying to convey in my post on Scripting vs. Engineering; software engineering (as opposed to mere scripting) is a team activity, not a solo one, and readability and clarity is everything even if the team is just you and your future self.
Here are some more ideas in that direction:
- “the glitz of such code just wastes time & brain cycles” related to the notion of modesty in elegance.
- “Thou shalt make thy program’s purpose and structure clear to thy fellow man by using the One True Brace Style, even if thou likest it not, for thy creativity is better used in solving problems than in creating beautiful new impediments to understanding.” (https://www.lysator.liu.se/c/ten-commandments.html but I think it’s older than that)
- Optimising for Human Understanding
- Without the comment, this bugfix wouldn’t make any sense (the bug caused 100% CPU usage deadloop and was introduced in an earlier fix, presumably because the original code wasn’t clear enough)
So how could my colleague and I have such a differing opinion ? Well, Matthew is great friend and an accomplished musician, and I have (some minor) aspirations of being an author – i.e. perhaps, like all people, we each understand and explain in terms of what we know. Unfortunately though, with my seemingly limited imagination I’m more likely to continue writing software and blogs than getting rich rich rich from that novel… Oh well, back to the creation.