Excellent. These are the kind of thought-provoking posts for which I come to this blog.
A software engineering professor of mine in the '80s used to harp on providing enough inline documentation and using meaningful variable names to ensure that a reasonably logical person (potentially without any computer science background) could read our code and understand: 1) what problem we were trying to solve, and 2) how we were solving it (potentially including why we chose to solve it that way or not to solve it another way). I later revised the criteria down (sadly, in some cases up) to a relatively intelligent nine-year old. Every time I was able to meet that criteria, I ended up with code that I knew I could pick up in six months and maintain without having to retrace steps and reinvent.
Much of programming is problem solving, which is what attracts many of us to it in the first place. When well written, the fact that we can compile and run our solution is almost incidental. Although, it does pay the billsā¦
Another benefit Iāve noticed is that when I try to make the code clearer, I often find ways to refactor it or notice logical inconsistencies that werenāt obvious before. When Iām really, really lucky I start finding sections of code I can eliminate entirely.
Sadly, many of my colleagues either are too unmotivated or have been seduced by what they understand of best practices to focus on making their code more readable. Some of the excuses are laughableāI donāt use long variable names because they take too long to type from someone that apparently doesnāt understand that even Notepad allows you to search and replace.
RANT
As I get older and more bitter, Iāve begun to rail against all sorts of (perceived) idiocy: āIF SomeBooleanVariable = FALSEā instead of āIF NOT SomeBooleanVariableā, several hundred line long routines, and can someone please tell me why āgRCā is supposed to more meaningful than āPageNotFoundā.
The problem with many of the legacy programs I have to maintain isnāt necessarily any of those or the host of other irritations swarming around them, but they have become a symptom and signpost of a disordered approach to solving a problem. Unfortunately, they spread from one program to another as theyāre copied as working examples simply because their inherent flaws havenāt been exposed yet.
/RANT
The point of software engineering (as opposed to pure coding) isnāt to completely eliminate bugs. Thatās frequently either impossible or impractical. Itās to make as many of the mistakes as early as possible in the development life cycle and learn from them how to isolate problems and leave enough clues when they happen that you can determine root causes.
Write your programs as if you were going to get called at 3:00am and needed to figure out what was going wrong and at least potentially how to fix it while your boss was waiting impatiently on the other end of the line. If you donāt, one day you will be.
To those commenting (or assuming) that many of those who program and are not native English write bad code. It may appear bad to you because they write for those who speak their natural tongue.
I agree. We should write code like Shakespeare. There is even a programming language for it: http://en.wikipedia.org/wiki/Shakespeare_programming_language
Itās not just useful when it comes to coding. Before you write code you have to decide what the code is going to do, and how itās going to work (even if roughly). If more than one person is involved, you need to have some sort of communication about that, ideally written. As the code is developed, you need further communication about changes, problems, bugs, and you need to document classes/interfaces/etc. Finally, and most importantly of all, you need to clearly communicate to users, sales/marketing, bosses, etc. all the important facts and details about the software, how to use it, what it does (and doesnāt do), etc.
Some of the murkiest problems and annoyances I encounter is indecipherable run on change requests, documentation, explanations, etc. And when that extends to users and sales/marketing, you end up with frustrated and dissatisfied customers.
Is it not why we ask our programmers to put in their inline comments to note what each function is doing? that makes it more readable, certainly.
This needs to be said: Strunk and White is a pox on the English language, a cancer that needs to be excised, purged, cursed, and spat upon. Imagine a programming book that included every bit of voodoo programming youāve ever seen, every ugly, uncommented, cut-and-paste script kiddie monstrosity compressed into a dense, reeking shitcake and spread on bread for your to call it honeyāthat is SW.
Perhaps my hyperbole got away from me there. Ahem.
Anyway, what I mean to say is that SW perpetuate all sorts of myths, half-truths and lies about English usage. Slavishly following their advice will make your writing obscure and pedantic, not clear and communicative. Just say no.
I couldnāt agree more Jeff. I canāt count the number of times Iāve looked into a codebase only to realize that the code was confusing and that the author(programmer) was as well. Iāve consistently seen this confusion lead to buggy and extremely error prone code.
Excellent book. Iāve heard programmers say good programs read like books many times, but when I see their codeā¦letās just say that we probably read different books. IMHO here is what it doesnāt mean:
Write your code anyway you like and litter it with comments explaining everything, itās clear just read the comments. This would be like a book littered with footnotes explaining whatās going on.
Clear != Simple. I sometimes get these confused myself. Clear code is easily understandable but could express a fairly complex idea, E=MC2 comes to mind. Simple code expresses a simple idea, Hello world is an example.
It shouldnāt be applied to just the syntax/grammar but it should also be applied to the overall structure of the program/book. ie. Removing duplicate code (even if itās clear) and putting it in one place.
Another parallel between writing and programming is that both require multiple drafts. You have to write, rewrite, revise, and edit. (In programming, many of those are called simply refactoring.) You have to build that into your schedule.
Yes, release early and often, but donāt put your first draft out there. All those mistakes will come back to haunt you.
This blog went from a great resource for like minds, to complete junk.
rssā;
I originally commented over at James Devlinās site, but if this issue is going to come up again, I feel the need to comment again
While they are both based around creating things, the essence of writing is very different from the essence of coding. Consistency and rigor make for great code, but horribly dull reading. Nouns drive elegance when programming, but force verbicide when writing. Coding requires a mathematical like dedication in construction, building on its history, while good writing follows its own unique path each time, avoiding what has gone before. Style is all important in writing, while it is convention that is really important in programming.
They are in most ways very opposite from each other, which is why you rarely find people who excel at both. Itās a left brain vs right brain difference.
Beyond that, it doesnāt scale either. Could you actually imagine a fictional novel written by twenty different authors? If they even managed to get it finished, it would be quite a mess. Yet, its not hard to imagine a house built by twenty different contractors, is it? Some things are individual pursuits, while others can be done by groups.
Paul.
As a long-time programmer/writer (I create documentation for SDKs as my bread-and-butter), I can attest to the correlation between clear writing and clear code. I have rarely seen outstanding code from someone who could not construct a coherent sentence. There are occasions where I have seen ESL (English as second language, or non-native) speakers who wrote good code, but had difficulty with some of the more esoteric elements of the English. Heck, Iāve seen many a born and bred in the USA developers who could not write a straightforward email missive if their life depended on it.
Methinks much of the issues with poorly written code would disappear if said developer could stomach a code review. Said reviews typically force devs to defend their spaghetti code and usually leads to much more readable code.
I too have seen the if(x == true) constructs among my colleagues. In one unfortunate case, I had to embarrass a coworker in front of the group when asked to resolve a bug I had filed on his code. The poor SOB did not even understand Boolean logic for crying out loud!
Some of Strunk and White is not entirely appropriate to SW development. Although in most cases I agree leaner is better, in SW you must also program defensively. For example, when calling a routine, you should first ensure that the args are not null, unless of course that is the point (as in testing the routine). Within a routine, you must be able to handle null args. Therefore, in both the caller and callee, each arg is compared to null, then an appropriate action is taken (maybe the caller does not call the routine, maybe the callee returns null).
And of course, you must document whether your routine can return null. Donāt surprise your caller/audience.
doug in Seattle
I was a lawyer before becoming a coder. Strunk and White always holds pride-of-place next to the Constitution on my bookshelf. But, I hadnāt thought about how writing may have informed my coding until this article. Definitely food for thought.
By the way, many people donāt seem to realize that E.B. White is the same E.B. White who wrote Charlotteās Web and Stuart Little. Read Charlotteās Web (to a child if youāre too embarrassed)if you want to see Strunk and White brought to life.
There is a huge difference between well written readable code and code ridden with documentation. In general, well written code should not need in-line documentation. Methods should be small and concise, surrounding a chunk of logic that can be easily expressed by its method name. Code within these methods should have descriptive well chosen variable names. With these two qualifiers, code is extremely easy to read and not bloated with unnecessary comments.
I also agree 100% on the non-native English speaking comments. I see a direct correlation between less readable code and non-native English speaking programmers. I am sure the same could be said for me if I moved to Europe or the like.
Good post. Yes we should write code so that other people understand it and also can see the structure easily. If someone applies some random custom design pattern, then how are we others supposed to know what is going on? Well, we need the design documents. Sure some things can be seen right from the code, but not everything. The more we see straight from the code, the better, but there should also be the design documents. The design documents can be simple too, but they should exist.
A similar classic: Tutorial on Good Lisp Programming Style by Norvig and Pitman.
I dunno, Iām going to go with Language Log and a couple of other commenters here and say that Strunk and White is the last model a programmer ought to be using; it belongs in the rubbish bin of history. Itās a really ridiculous book and Geoff Pullum nails the problem perfectly: The Elements of Style offers prejudiced pronouncements on a rather small number of topics, frequently unsupported, and unsupportable, by evidence. It simply isnāt true that the constructions they instruct you not to use are not used by good writers. (http://itre.cis.upenn.edu/~myl/languagelog/archives/001803.html) He also points out that the authors frequently break their own rules mere pages after those rules are defined. The premise of your post is good, but those who would follow Knuthās style of Literate Programming would be advised to have nothing to do with Strunk White.
I think that the effort that goes into literate programming pays for itself many times over. I have found though that it is a fairly thankless endeavor. Well-crafted code organizes and simplifies the concepts, and is consequently taken for granted. Like a good lens, you see the subject more clearly, not the lens itself.
Then to add injury to insult, how often have you seen a colleague quickly grasp your concise, cohesive, and test covered code, and proceed to extend it by tossing in unrelated concerns and with junk variable names? Sigh.