Push Button Paradise

Micah Dubinko

Sun, 24 Jul 2005

Patternalia - Identifiable Neighborhoods (Project Pattern)

In source code projects, standard practice is to have rigid "coding style guides" to dictate every little detail about how code should be laid out on a page or the screen. This pattern describes the effect this practice has on overall navigation.

This essay is written in terms of coding guidelines, so it's worth spending a few paragraphs describing exactly what this means. Source code is a human-readable description of some kind of software or computation. Some parts of the code are "functional", which means that they describe exactly what the program does--in other words, changing a functional part of the code may cause a malfunction. Therefore, very little, if any, variation is possible within the functional aspect of source code, save for bug fixing or changing the underlying specification of what the software is supposed to do. As a crude example, if the computation is "2+3", changing any of "2", "+", or "3" will have a serious effect. Arguably, the key thing programmers get paid for is crafting the functional code to meet specifications.

[A note for software experts: "functional", as the word is used descriptively here, doesn't necessarily have anything to do with "functional programming", which is a specific paradigm that considers computation to be the result of evaluating mathematical functions.]

On the other hand, other parts of the code, for example the choice of how many spaces to indent things, ways to name storage areas, and so on, are much less tightly controlled, and can be changed according to the tastes of the human programmer usually without affecting how the resulting program operates. Continuing the crude example for the computation of "2+3", adding spaces around the "+" generally won't affect the result. Such details are considered an area of "style".

Of course, for the human programmer, having a readable style is critical in order to grasp how the code functions and be able to work with it. As a crude example, if all insignificant whitespace were removed from code, it would still compile fine--that is, the computer would be able to work with it the same as ever--but human programmers would have a terrible time figuring it out. So having a readable style is important.

In a big project with multiple programmers, how important is having a strictly uniform set of coding style guidelines? Programmers are notably passionate about such questions, going all the way back to the 1978 classic The Elements of Programming Style by Brian Kernighan and P. J. Plauger (see links). A great number of these, like "Say what you mean" and "Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?" are simple truths that come to be realized by any experienced-enough programmer.

Other aspects of style really are matters of taste. All too often, these are written by an overly-dogmatic lead engineer who delights in imposing his or her will on others. In the absence of strong enforcement, though, individual programmers tend to settle into their own individual styles. One might write fairly dense, rich code. Another might write more airy gracefully flowing code. As long as either one works the same, how much does it matter if the style is different?

Even for someone not a native New Yorker, a photo of Midtown Manhattan would be easy to tell from a photo of, say, the Bronx. Neighborhoods thankfully aren't all identical. Imagine yourself, unfamiliar with New York, trying to drive to Manhattan--looking around and seeing the surroundings of the Bronx would be a good sign that something was amiss. In other words, differences in styles are actually useful as a coarse navigation aid. If every possible neighborhood had an identical look and feel, strictly enforced, the result would be on almost Orwellian nightmare and as a result, navigation would be much more difficult.

Source code offers many parallels. In many cases, it's possible to tell when two different people wrote two adjacent sections of code. This can be a benefit. Once a programmer gets more familiar with a code base, a quick glance at the text editor can give an immediate, intuitive feel for what portion of the overall program is the "current location". If a neighborhood of code has such an unusual style that it imposes difficulties on visitors, then by definition the code is not of high quality and should be re-written, and greater attention given to the programmer who originally inserted it.

When modifying code, programmers tend to fall into continuing the native style. As a result, projects which don't spend large amounts of time enforcing style tend to clump into identifiable neighborhoods of code. Rather than fighting against this tendency, perhaps it should be embraced for the energy and character it can add.

Therefore:

Code style guides should encourage "common sense" things, like producing readable code and making common mistakes stand out. Code reviews should focus on functional aspects and beneficial style aspects of code, never nitpicking on things like how many spaces should be between certain punctuation characters. In effect, the only enforceable style guideline should be "write good code". All traces of dogmatic style guidelines should be rooted out.

If different portions of a large program develop different intuitive feels, this should be encouraged and maintained.

Now, the distinction between functional aspects and still-important style aspects isn't limited to source code. Other endeavors have similar aspects. However, for concreteness, this essay is sticking to the source code discussion. Applying this pattern to an even broader field is left as an exercise for the reader--or perhaps a future Patternalia.

About this article series: This article series is being provided at no cost on the internet. To show your support,

Become a regular reader, including any back-articles you've missed.
Link to it; tell your friends to read it and link to it.
Buy things from the advertisements on this page.
Leave encouraging feedback.

All articles will appear underneath http://dubinko.info/blog/patternalia

Amazon associate links:

(Research tip: check out the reviews on some of these)

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License.

posted at: 22:34 | under: patternalia | 0 comment(s)