How to write… software 21 Jul 2005

19 comments Latest by vicky

“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.” -The Elements of Style by William Strunk Jr. 1959.

19 comments so far (Jump to latest)

Jonathan 22 Jul 05

Google Ads ? Where ? Oh sorry I’m using AdBlock ;-)

Art Wells 22 Jul 05

Software /is/ writing. If you write machine language, it’s only different from the way you write human language because you don’t know anybody who is so good at reading what’s written while being so unable to read what isn’t.

Christopher Fahey 22 Jul 05

It’s funny, I’ve always considered The Elements of Style to be one of the best examples of the tendency of the English language to become “codified” for the sake of precision , uniformity, and clarity. And by “codified” I mean “to become like code”.

One of the reasons why older English literature is often hard for modern readers to understand is because the English language, the actual technology of the written and spoken word, was a little bit more primitive in earlier eras. Before the invention of the dictionary, there were simply no rules about spelling - not even about the spelling of proper names! In 19th century novels, you’ll see a dozen different methods of quotation syntax (single quotes inside double quotes, double quotes inside single quotes, no quotes at all, various flavors of brackets (e.g.

But as with all other technologies, English was “improved” through standardization. Through the invention of spelling and grammar rules, and academies to define those rules, English got crisper and clearer. But some would say it also lost something when it lost that legacy ambiguity. Maybe it’s a slippery slope from codification to Orwell’s “newspeak”, where all ambiguity is removed. Is the streamlining of our language turning it into computer code, forcing humans to think like computers?

I think we’re still a long way from that, usually to my chagrin. As a dilettante programmer myself, I seek a kind of rigid clarity to my English grammar and punctuation that Strunk & White don’t even come close to. For example, it still annoys me that we put commas inside of of quotes instead of on the outside, where they logically belong (because the comma is not part of the quote — it’s part of the sentence invoking the quote). Strunk & White would probably have a heart attack over the nested parentheses I use all the time in my writing, even in this post!

Anyway, I predict that the grammar and style of our languages, English and many others, will soon be radically changed by what society has learned by writing so much computer code.


Christopher Fahey 22 Jul 05

The last part of my second paragraph above was totally wiped out because I used a greater-than sign in my text. The blog software thought it was HTML and killed it.

A perfectly legitimate and common 19th century punctuation mark is apparently now illegal in computerworld, proving my point!


Ryan Heneise 22 Jul 05

However, in the hands of the wrong person, even the Elements of Style can be dangerous. It is easy to wind up at the other extreme - which would be to say to little, to actually omit *needed* words (or features), and end with a sentence (or product) that has no useful purpose.

In other words, I agree that “vigorous writing is concise”, but I would add that _vigorous writing (and software) is *deliberate* and concise_.

Erik 22 Jul 05

Two of the largest codifiers of the English language were Chaucer and Shakespeare. Take a look at Shakespeare’s contemporaries. Spencer particularly liked to use a ‘y’ where Shakespeare liked ‘i’. At the time, it was a matter of preference, not of codified spelling.

The tendency in modern literature has been more to set standards than to ‘codify’. Strunk & White, in my opinion, is just a way for people to agree upon a way to communicate. With the number of people now capable of producing written material (as opposed to the, say, 14th century, when cloistered monks were largely the only people really interested in producing it), such agreements are important. Could you imagine if every writer on the internet decided that they were going to come up with their own way to use different puctuation? You wouldn’t be able to read anything.

You can see it in some the l33t type writing going on nowadays by haxors. They have their own agreement on how to write, one that expects the reader to bring more to the table. Most readers are too lazy to put that kind of effort into reading anything other than the latest Harry Potter.

What does this have to do with programming? Well, look at perl. In just about every script, you have at least three different ways of writing the same functionality. Perl is the English of the programming world. Look at a word like “bad” in the English language. Now look at the number of synonyms (sucks, blows, horrible, terrible, crappy, etc.). Each of them mean the same thing in essence, but have a different connotation. In perl, somethnig similar would be an ‘if’ statement. I personally love to us ternary operators to assign variables. Or, you can use something like:

print x if (x > y);

Alternate ways to state the same kinds of things.

Ruby allows for a much more concise writing style than most languages. (Perl does too, but perl also lets you go crazy in the opposite direction in a way that ruby doesn’t seem to.)

Code writing is a much more personal thing for most people, I think, when it comes to style, than the style of our written language. Most coders really only intend the code to be read by a very different audience than written English: the computer. Computers tell you immediately (especially in dynamic languages) when they don’t understand something. But they understand a wider variety of statements. You can do the equivalent of talking like Yoda to a computer if that’s the way you like to talk to computers, and the computer doesn’t care. Do that in English with a friend, and at first they’ll laugh, and after two weeks start to talk behind your back.

So what I’m taking away from this post is that we should expect that your code is going to be read by another human at some point, and concise code allows for better human readability. If you don’t have to wade through 200 variables, for example, some of which are used only once, it’s much easier to understand. And probably, it runs cleaner as well.

Christopher Fahey 22 Jul 05

Erik, good thoughts about Ye Olde English! My wife has been studying a little Chaucer recently. At the time of Chaucer, French and English were still in the midst of the cultural collision that gave birth to the modern English tongue. So even the words themselves were very much in flux. The snowball effect of increasing literacy and the explosion of the written word brought about by Gutenberg were clearly the biggest reasons behind the standardization of most languages.

By the way, it’s funny that you like ternary operators and you advocate for human readable code! I remember when I was first learning to code, ternary operators seemed like a way for elite programmers to make their code more inaccessible to newbies trying to find normal conditionals!


avpicov 22 Jul 05

To me, software is more like dominoes then writing. You simply set up the pieces in a prearranged fashion, flick a switch an wallah…. you have a program.

The best and worst thing with software today is that my dominoes look different then everyone elses. And they don’t always work together.

Tommy 22 Jul 05

I’ll second on Writing Well´┐Ż by William Zinsser. It is an enjoyable read. I have to write more then a little for work, and I know I am not good as I should be, but alas we all wear a lot of hats.

When I revist a first draft I may remove 30, 40, even 50 percent of the copy. But I am always asked to add more and more words.

From my POV I see three problems with copy on the web:

(1) Not well written.

(2) Assumes the audience is dumb, so the copy over explains stuff and uses too many words.

(3) It doesn’t tell a story (Seth Godin’s matra), but instead includes bulleted list of features after bulleted list of features.

IMHO 37Signals has some of the best copy on the web. It informs, yet it is enjoyable to read.

Brian 22 Jul 05

I’ll throw out “Politics and the English Language” as a favorite, in consideration of “language as an instrument for expressing and not for concealing or preventing thought.”

Brad 22 Jul 05

Also in the Elements of Style is this little gem:

The whole duty of a writer is to please and satisfy himself, and the true writer always plays to an audience of one. Let him start sniffing the air, or glancing at the Trend Machine, and he is as good as dead, though he may make a nice living.

A useful warning to writers of both prose and code to resist blindly following fads and jumping on the latest bandwagon.

Robert Hoekman, Jr. 22 Jul 05

Ahh, but most developers would be inclined to add more and more features in the hope to “please and satisfy himself”. It takes a finicky audience to compel him to chizel away at the application until it becomes a master sculpture.

Don Schenck 22 Jul 05

Thou dost protesteth too much.

craft 29 Jul 05

so the graphic design guys are now giving out instructions on the proper way to write software? how about software programmers telling the world how to design? basecamp aside i’d say get a little more scar tissue than you curently have before getting precious about code slinging

Moore 25 May 06

This is a good service/website to help you with any writing assignments:

vicky 04 Aug 06

hi dude thanx for this