I’m giving a presentation on Lucene.NET in two weeks, which has me thinking about coding for an audience. For the most part, we developer types write code for a compiler or interpreter. We write for the computer, and the computer doesn’t really care about style or coding conventions or readability. As long as the syntax parses, the machine doesn’t care that the instructions are a mess.Other humans do care about these things, however. And those other humans are actually your most important readers. One of those other humans may in fact be your future self, revisiting a block of code you wrote months or years ago. Those other humans are your true audience, not the slab of silicon and liquid crystal in front of you.
While it might be tempting to minify or obscure your code, or to just commit-it-and-ship-it as soon as you have a hack that approximately works, the poor slobs on the maintenance team or your bored peers in the code review session are going to look at the sloppy work and roll their eyes.
So it’s a good idea to write human-readable code. It’s too bad that there’s no general consensus around what makes code readable, as John Somnez pointed out this week on DZone. Or rather, what makes code readable might differ depending on your audience. Different populations of developers will have different expectations for your code.
Beginner code monkeys want to see simple constructs, with little of the syntactic sugar that advanced programmers use to conserve keystrokes. They are struggling to understand the basic control flow of the program, and the last thing they need to see is your fancy ternary operator instead of a straightforward if/else statement.
But it isn’t just the experience level of the audience you have to consider. It’s the role the audience plays in your code. Are they business analysts? If so, your class names and methods ought to map closely to your domain model. Is it system administrators? I hope your configuration files use familiar settings found in familiar sections of the code.
For the purposes of demonstration, it might make sense to write one long procedure that you can walk through step-by-step, with annotations along the way. If the intent is for the code to be unit tested or extended by a third party, you’ll want to break your code apart into simple, reusable chunks that can be assembled in different ways.
The code shown at conferences or on most websites has been stripped down to remove distractions and get the key points across, but true production code will have have comments, error handling, setup and teardown routines, and any number of other constructs to defend the system against the hard knocks of actual use. Show the former version of the code if you want to build excitement around your new, clean API. Show the latter when you’re trying to explain to your boss why the system can’t be rebuilt in a week.
Writing code is just writing. Like crafting a good essay or newspaper article, you have to keep your readers in mind.