Home (contents) → Miscellaneous → Technical Writing and Programming → Source code and prose
Source code and prose
Disclaimer: The views expressed on this page are mine and do not necessarily accord with those of any of my employers, past or present.
I have sometimes encountered the belief that computer programming and clear human communication are distinct skills. On the contrary, program source code that is easy to understand is likely to have fewer faults, be more efficient, and it is almost certainly more ‘maintainable’. Also, its end user interface (if it has one) is more likely to be well crafted and, therefore, easy to understand and to use.
Programmers of user interfaces must be conversant with technical writing standards. Indeed, as the cost of human labour continues to rise in comparison with the cost of the systems we use, the need for highly usable interfaces becomes more critical. However, that need is nothing new. When airliner cockpits became highly complex in the 1950s and early 1960s, especially with the introduction of jets, fatal accidents were caused by ill thought out panel layouts (rows of identical switches for disparate and critical functions).
When, in the late 1980s (and even into the 1990s) I attempted to steer my fellow programmers away from using cryptic names (along with global variables) I showed them my Turbo Pascal source code with CamelCase names for its sub-programs, variables, and the rest. Often those names were long, but explicit and easily readable.
The normal reaction it elicited in those colleagues was spontaneous and genuine laughter. “You can’t do that!” More laughter.
Given that there was no actual humour involved, I suspect that the laughter was rooted in something like embarrassment. (Research by V.S. Ramachandran indicates that humour is at least partly a result of phenomena that, on first sight, appear to be one thing — your passport to an exclusive ‘in crowd’ perhaps — that suddenly reveals itself to be the opposite — a fee pass for anyone and everyone to join that ‘in crowd’.)
Here is a snippet from my still unpublished novel, set on an Earth-like planet 300 years from now:
He was promoted to team leader and the firm hired more programmers. Some, although familiar with the programming language they used, were unwilling to follow conventional programming practice as advocated by organisations such as the Sigma7 Association for Computing Machinery (SACM). He asked Wally, a soft-spoken and affable man with large square spectacles who was employed on a short-term contract at four times Neil’s pay, his reasoning about the issue.
“Aha! You’ve got to learn, even as a permanent employee, you don’t work for your employer, you work for yourself. Next you’re going to ask why I use one- and two-letter acronyms for variables instead of giving them meaningful names other programmers can understand. So if I get run over by a bus somebody can pick up the project.”
“Exactly.”
“It’s so other people can’t understand it. Hell, even I can’t understand it if I come back to it after a month away. Therefore I’m indispensable. How do you think I can afford a wife, seven children, a house in the country, and a kept woman in town? And if I get run over by a bus why should I care what happens to it?”
The problem, it seems to me, is where the author (programmer) views his work as his private property. Most programmers seem to be like that, at least at first. However, in programming, like learning to ski or to fly a hang glider, you have to overcome some instincts. It requires training and practice. To paraphrase a former US hang gliding champion and author, the skilled programmer uses his superior judgement to avoid having to use his superior programming skills.
For example, user-centred design requires you to adopt a ‘what, not how’ approach. The beginner programmer, asked to describe what his piece of code does, cannot help himself (or herself) from describing the workings of that code (the ‘how’). To resist that temptation — and to even recognize that there is a difference between the what and the how — requires practice. (You have two principal types of user: End users and other programmers. I have never encountered a situation where catering to those two groups conflicts.)
Having said all that, there is no silver bullet. There are other types of individual to whom your code (or prose) will make no sense, no matter how explicit and clear it is. For example, those with mathematical minds are more comfortable with abbreviations and hieroglyphics.
Brave Guys and Beautiful Dolls 