Why I think some coding tricks are especially damaging

November 21, 2010

Over time, I've come to the opinion that some programming tricks are more damaging to your code's readability than others. I think that there are at least two sorts of coding tricks, which I will call opaque tricks and impossible tricks, and impossible tricks are more damaging than opaque tricks.

An opaque trick is one where the reader stares at the code and has no idea what it does. Either they don't understand the operations, or they don't understand what the results of doing the operations are (perhaps you are playing odd bit tricks), or they can't follow the flow of control, or any number of other things that leave them lost. An impossible trick is one where you do something that ought to be impossible, except that clearly it works because your code runs; for example, in Python you use something from a module without explicitly importing it.

(Sometimes these categories overlap in actual code.)

The problem with impossible tricks is that they destroy the reader's confidence in their understanding of the code. Since something that you thought is impossible is happening anyways, clearly your understanding of the code to date is incorrect and you've missed something important while reading the code; you need to start over, more carefully and cautiously. In effect, an impossible trick damages or destroys the reader's confidence in everything they think that they know or have worked out about your code.

By contrast, opaque code is just a local issue. The reader knows that they don't understand this code and they're going to have to study it carefully (or trust the comments), but their understanding of other code is undamaged; their uncertainty is local instead of complete. Someone who is skimming can even skip working out how the code works and just assume that it does (which is fine as long as they don't need to change or debug it).

Written on 21 November 2010.
« Why I avoid DSA when I have a choice
Where to find the Illumos source repository »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sun Nov 21 23:15:14 2010
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.