(And just to note, as someone who has now teaches kids of all backgrounds at an Ivy League institution and has to grade their essays. Most of them out of high school cannot write and do not know basic grammar. Many are painfully inarticulate in their speech and written work. It is pretty sad stuff. Even with the best of the best I end up sending half of my students to writing tutors.)
enter ruby, the concise programming language…
Writing is closely related to thinking. To be clear with language is usually to be clear in thought. Unfortunately this is not how English has been taught in American public schools for a number of decades now. Students are instead taught that the point of literature is emotion (not language), and do pointless exercises trying to figure out how Romeo and Juliet felt and how the student feels when they read about how they felt. And from a testing point of view, they are taught that language is nothing but memorization of vocabulary, elaborate diction that has little place in the modern world other than on standardized tests.
It is a perfect recipe for a society which sorely lacks for critical reasoning skills, as well as writing ability. And it has led to an entire generation of students who think that literature is just an assignment a teacher gives you.
Sigh. OK. Rant over. How this ties into coding, I’m not entirely sure, but there we have it!
My four rules of programming are: Keep it clean, neat, concise and coherent.
Everything else is just fluff…
I find Style: Toward Clarity and Grace (http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishing/dp/0226899152) excellent too. I keep a copy of both in my desk at all times.
I saw your code. It looked easy. It’s just a bunch of typing. And don’t get me started on your overuse of semicolons.
Not everyone worships Strunk and White, of course. In particular,
some linguists don’t seem to like the work:
(sometimes parents give their children copies of Strunk and White to
take off to college, a practice I believe constitutes child abuse)
(from http://itre.cis.upenn.edu/~myl/languagelog/archives/004176.html)
My late friend and co-worker John Stoddard always said The difference between a good software engineer and an great software engineer is that the latter wields a word processor as well as he does a compiler.
This is an interesting post. In my first CS class in college, my professor had us stop writing all code for the first two weeks, and we wrote a ten-page paper using pseudocode for a small calculator program using LaTeX. We then went back and added our C code so that we could extract from the same document our source and a nicely formatted PostScript document.
At first, I thought he was nuts. Ten pages for a calculator program? Ten years, later, I now write very thorough comments and documentation because of that training. I’m often made fun of at first… then praised for having documented my code so well while everyone else is told to comment more like me.
Is it a requirement? I think that depends on time. Obviously, we’d all like to write perfectly architected applications, but sometimes, cost and time constraints prevent that. I think the same proves true with code documentation. Of course, those constraints don’t mean we shouldn’t strive for the goal.
Great article!
I can’t believe it, I actually beat Jeff to the punch (kind of)…
http://frankkoehl.com/2008/04/writing-modular-code-make-it-legible/
Obviously I support your point of view 100%
Jeff, thanks for writing on this important topic. In my opinion, the importance of writing code for the people who must read and maintain it does not get the emphasis and attention it deserves.
I advocate writing every piece of code as if a co-worker, perhaps one less experienced than one’s self, was going to have to read and then very quickly understand it, probably without the benefit of having its author on-hand to explain it.
You have a good point! 
It’s interesting, because a few years ago I researched how to reduce spreadsheet error and make them safer. After reading everything I could about both spreadsheets and programming in general, I came to the conclusion that I could reduce good practice to two simple rules
- make spreadsheets easy to check, and
- make them safe to use (and maintain)
Both of these are very much about recognising that you are building your spreadsheet for someone else to check or use. It’s not for you at all. And both these guidelines are about people rather than being technical. Which is in tune with your post.
I advocate writing every piece of code as if a co-worker, perhaps one less experienced than one’s self, was going to have to read and then very quickly understand it, probably without the benefit of having its author on-hand to explain it.
Someone with less familiarity with the code than the writer (you) is going to have to read it later … you in a years time …
That’s the point of well written code, you should be able to understand it quickly so you can debug/enhance/change it, without having to rewite it because it is not understandable
I think that writing code and writing both require a thorough understanding of what you’re writing about and what your goal in writing it is. If you really understand what you’re writing about and why, you’re a long way toward writing well and writing good code. The unnecessary parts of your writing creep in when you can’t figure out what’s really necessary to meet your goal, not because people enjoy throwing in extra loops and variables.
A philosophy professor of mine once gave me some excellent writing advice that I try to apply to writing and writing code. Paraphrased: Don’t just write so that you can be understood; write so that you cannot be misunderstood.
Writing is closely related to thinking. To be clear with language is usually to be clear in thought. Unfortunately this is not how English has been taught in American public schools for a number of decades now. Students are instead taught that the point of literature is emotion (not language), and do pointless exercises trying to figure out how Romeo and Juliet felt and how the student feels when they read about how they felt. And from a testing point of view, they are taught that language is nothing but memorization of vocabulary, elaborate diction that has little place in the modern world other than on standardized tests. -Shmork
Ok, so to relate this to coding, the point of making students attempt to emphasize with characters in books is to help them better remember facts and WHY those characters are doing what they’re doing. In code this means figuring out why the programmer has a function that removes all the curly braces in a form submit post. Or why they have a function that retrieves a standard string over and over. Being able to emphasize with the programmer will lead to a greater understanding of the code.
I also don’t know what American schools you went to, but vocabulary tests were only done in elementary school and a little in middle school in my area. You have to be able to read first in order to understand later 
The tests I took with the exception of foreign language tests had little to nothing to do with memorization during high school and quite a bit more to due with critical thinking and application of knowledge.
Another correlation:
I was struck by the quality of Linus Torvalds’ writing on his new blog (http://torvalds-family.blogspot.com/). It is safe to say he is an excellent programmer, and it turns out, an excellent writer as well.
You are so correct. Strunk and White holds a key place in my house. I originally went into college to get a degree in CS and came out with a degree in technical journalism, only getting back to my first love of programming about 10 years ago. The trick isn’t so much doing the writing, but making it readable.
With so much code being done around the world by folks who have the programming chops (hopefully) but speak English as a second language, all too often it’s very difficult to understand what was meant vs. what was written. Spelling errors, grammatical errors, and so on are very context-specific. Even with a few spelling errors, if the message is clear, that’s 90% of the battle.
Omitting needless words is important to clear expression, but in most cases it’s even more mundane than that.
SVO. Subject verb object. The structure of the basic sentence boiled down to its basic parts of speech. If more people understood this simple formula for writing a sentence, we’d be so much better off.
Thanks for a thought provoking post!
This is a long held belief of my own. In fact I first came across refactoring under the term Sub Editing when working for a paper. Watching a skilled sub-editor at work is akin to seeing top refactorers: they continously make small changes whic improve the structure: move words, delete some, re-order the sentance, remove some, move the sentances in a paragraph around, re-order some paragraphs and before you know it a 1000 word essay becomes a consice, clear 200 word article.