I’m in the middle of another round of “Source Code Style Guidelines”, with my co-workers. We know what this means, “Rule One: No Edged Weapons”.
Most of my education has been aimed at science and engineering. Nevertheless, I’ve come to the conclusion that most technically trained people, and especially math majors, are not cut out for programming. This does not mean that their programs don’t work, or aren’t elegant. The problem is more subtle, they simply haven’t the communications skills for it. Program source has few readers, but most programmers assume that their entire audience is the compiler, that piece of software able to parse a programming language, translating program files to machine instructions, a long series of numbers and data which can be executed directly by the computer. At a minimum, most computer programs have these audiences:
It’s easy and great fun to join in the religious source wars, arguing about angels and pinheads. It’s much harder to remember your readers and actually write for them. With so few reading your code, it is all the more important that every element of style should address these readers, no rule should exist which does not serve them.
The mechanics of programming, of writing source parsable by the compiler can be easily embraced by anyone with a logical mind. Writing for human audiences is a much tougher proposition. Writing for humans is so hard to do well that good writers are much rarer than good mathematicians.
Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short or avoid all detail and treat subjects only in outline, but that every word tell.
Make the paragraph the unit of composition: one paragraph to each topic
As a rule, begin each paragraph with a topic sentence; end it in conformity with the beginning
Use the active voice
Put statements in positive form
Omit needless words
Avoid a succession of loose sentences
Express co-ordinate ideas in similar form
Keep related words together
In summaries, keep to one tense
Place the emphatic words of a sentence at the end
Oliver Strunk, The Elements of Style 1918
E.B White, adding to the 1935 edition of Strunk’s little book, appended these simple prescriptives:
1. Place yourself in the background.
2. Write in a way that comes naturally.
3. Work from a suitable design.
4. Write with nouns and verbs.
5. Revise and rewrite.
6. Do not overwrite.
7. Do not overstate.
8. Avoid the use of qualifiers.
9. Do not affect a breezy manner.
10. Use orthodox spelling.
11. Do not explain too much.
12. Do not construct awkward adverbs.
13. Make sure the reader knows who is speaking.
14. Avoid fancy words.
15. Do not use dialect unless your ear is good.
16. Be clear.
17. Do not inject opinion.
18. Use figures of speech sparingly.
19. Do not take shortcuts at the cost of clarity.
20. Avoid foreign languages.
21. Prefer the standard to the offbeat.
E.B White, The Elements of Style, 1935
It’s no coincidence that these edicts map almost perfectly to common coding guidelines, “The Elements of Style” has been heavily quoted, sometimes to the point of parody, by hundreds of books on programming. Published in 1974, Kernighan and Plauger’s The Elements of Programming Style might have been the first. While its examples were written in Fortran and PL/1, this seminal book laid out most of the precepts followed to this day. Here’s a few that might seem especially familiar:
“Make your programs read from top to bottom”
“Take care to branch the right way on equality”
“Test input for validity and plausibility”
“Don’t patch bad code – rewrite it”
“Don’t stop with your first draft”
“Modularize. Use subroutines.”
“Each module should do one thing well.”
“Make sure code and comments agree.”
“Don’t over-comment.”
Kernighan and Plauger, The Elements of Programming Style
Kernighan and Plauger did not spend a lot of time on minutia, they were far more concerned with clarity of intent than with placement of braces. Interestingly, in some camps, The Bell Labs C and Unix developers, Thompson, Ritchie, Kernighan and Plauger (Plauger didn’t actually work for Bell) and their many fans, have been accused of ”excessive literacy” It’s hard to say whether this is a swipe from the Mac/Windows point-and-poke crowd, or a swipe at the astonishing illiteracy of so many american engineers (Redmond leaps to mind here.)
For all that the Bell Labs crowd has been accused of excess purity, of being too ”academic”, of style over substance, it’s obvious in retrospect that this was a very pragmatic group of people. They developed solutions that were just good enough, ”The Jersey Approach”, in stark contrast to the ivory tower efforts at MIT, ”The Right Thing”, Which took so long to get right, and then deliver, that the computer science world had gone on without them.
The most important rule cannot be expressed as an element of style, it is “Write literature, write with passion, write to your audience, make your ideas come alive in their minds.” Sadly, this can barely be taught, hardly be learned, and is mostly lost in the rush to publish. And sometimes of course, it’s just hard to be passionate about folding in driver support for the Acme 2100 auto-binding color network printer/copier/scanner, with optional postage meter. Yet such is our lot, so we must gird our loins, and carry our flimsy weapons into battle against the ravening machine.
* * *
Another technology news article has surfaced at Forbes which turns out to be neither news nor technology. Brian Caulfield writes:
Deaf Leopard
...A true Apple fanatic will tell you that everything your Windows machine can do, Apple did first or does better. The worst part: The fanatic is often right….Microsoft is building speech recognition…Ford’s new Sync system, built with help from Microsoft, gives drivers the ability to control their electronics and even dictate text messages from the driver’s seat. It is part of an effort by Microsoft to extend its software far beyond the desktop…..So remember …[OS X]....looks great, and most reviewers are saying its home networking and backup capabilities are a step up from Vista. But have you driven a Mac, lately?
I recommend reading the whole piece over at Forbes, it’ll only take a few seconds…Back already? lotta news packed in that little story hmmm…
Time for a little deconstruction: The news in the story is that an american car builder is adding speech reco to some models.
The news that’s NOT in the story:
And who have these bright stars teamed up with?
So we’ve an article in Forbes that’s actually about a failing car builder trying to spruce up its image by buying embedded technology from a company with a long history of failure in the mobile and embedded marketplaces….
...Which somehow becomes, “Look, Apple is mostly better at everything, but Microsoft sold Ford this nice speech recognition that works...kinda…
Where does this stuff come from? How does this pass for journalism? Can the Forbes readers, supposed captains of industry, be so dim that they miss the actual story while chuckling over the dig at Apple?
* * *
Ashoney was healthy until late this week, when it became apparent that she was having coordination problems and a lot of pain. The pain meds the vet prescribed didn’t help her, she wasn’t eating or drinking, had only partial use of her back legs, and had barely strength to deliver her signature cry. This morning Nae and I, weeping and blubbering, agreed we couldn’t subject her to any more misery, said goodbye, and gave the vet the nod. Her final rest is with a few old friends under our avocado tree.
We’ll miss her, a lot, she was a fine feline friend to us for almost 20 years.
P.S. Ashoney means smoke in Hebrew.
* * *
The Fake Steve Jobs blog (FSJ) has been getting some attention lately, from mac, PC, and linux fanbois, the press, and especially from Forbes magazine, which gleefully quotes it.
And the blog is pretty funny, though sometimes I think I’m seeing it exactly backwards from its intent. I mostly think it’s an effort to lampoon Jobs, Apple, and their fans, but it seems to miss that mark pretty regularly. Or maybe the writer is really poking at the whole industry. In this story his target certainly isn’t Jobs. This may be a wonderful example of that strange way bias shapes perception
When the Apple detractors read it, they see Jobs, the pompous arrogant SOB, who should die and be hauled under Microsoft’s keel, for having the audacity to compete with Windows and the Zune and for strong-arming the poor abused music industry. The guy just blabs on about how smart he is, stupid others are, how nobody appreciates him, but f—k ‘em anyway…
But when Apple fans read it, they see Jobs, the pompous arrogant SOB, who’s vision seems to drill right to the core of consumer desire and design integrity, who sets incredibly high standards for himself and those around him, who sheds great ideas the way Gates sheds dandruff, who has no patience for fools….
Especially funny in the first post linked above, is the apparent assumption that readers might have sympathy for Doug Morris. As the head of Universal Music, he’s a bully famous for rabid abuse of mothers, and an ardent RIAA and DMCA supporter. Depicting him as a victim to Job’s arrogant manipulation of the music industry is laugh-out-loud funny.
The more you poke at this blog the weirder it gets, FSJ is Daniel Lyons, a Forbes columnist, and infamous corporate shill. He’s known for bilious rants against Linux and the GPL, for laughable fact (non) checking, and for inventing news and trends. Reading his Forbes columns alongside the FSJ blog you have to wonder if he has any actual opinions, if he’s on the Microsoft payroll, or the Apple payroll, or if his masters at Forbes have a clue that one of their lapdogs is losing his mind and trashing their advertisers. And yet, even when he’s writing lies and propaganda he’s funny, and manages to slip in a little truth. There’s interesting background on Lyons here, and here.
* * *
One of the most hotly contested sections of the “Digital Millennium Copyright Act (DMCA)” is the criminalization of any circumvention of Digital Rights Management (DRM) features, even when there is no infringement of copyright itself. So even if you’ve not violated copyright, any act that might interfere with some hokey copy protection scheme, e.g. Sony’s rootkit, would constitute a crime.
I’m currently involved in the design and implementation of system software (e.g. device drivers) for Vista and Longhorn. (Needless to say I’ve not had time for awhile (a long while) to write about furniture and interiors.) Hardware and system software vendors have to go through a tedious and annoying process of ‘signing’ their drivers, essentially getting M’soft approval for their stuff. Microsoft would have you believe that these signed drivers exist to protect users from viruses and trojan horses. Nothing could be further from the truth, almost all the new security features in Vista exist to enforce draconian censorship of any content that might (emphasize MIGHT) be pirated. Vista contains a great deal of code whose only purpose in life is to evaluate the possibility that you’re doing something evil with your computer and attempt to circumvent you. (Evil is defined as anything Microsoft, the MPAA, or the RIAA don’t care for, and includes doing things like playing your newly purchased HD movie on your hi-res computer display.)
Many aftermarket software products deliver applications and digital content from servers running Longhorn and Win2003. In order to do this, the developers must write ‘virtual drivers’ to span the connections between computers. In other words, they must hook the MS-windows ‘media chain’, adding the capability to re-vector content to a remote computer. Guess what? The DMCA probably makes doing this illegal. Once again, honest people trying to do perfectly acceptable “fair use” viewing of their own content will be seen as criminals, and probably denied access to the content they’ve purchased.
* * *