It’s difficult to believe that Reg Braithwaite wrote Programming conventions as signals more than five months ago. It’s been haunting my mind ever since I read it, as only newly acquired insights are wont to do. I find myself repeating the idea to colleagues and clients on a daily basis. It’s so simple and obvious that someone should have said it long ago — which is what makes it a great idea.
But I need a name for it, because our industry doesn’t have enough buzzwords. No really, having a label for this philosophy will help me to talk about it. I’d like to call it “thelophanic convention” (from Greek thelo = “intent” + phanos = “apparent”), because Reg’s idea is to use programming conventions in ways that elucidate your intentions (phanos originally meant a torch or lamp, but came to be used for “appearing” — so I like the notion of “illuminating” that this etymology adds).
In a nutshell, thelophanic convention means that when you have more than one way to do something, choose the way that best communicates your intentions. When there isn’t an apparent winner, decide on what each convention should mean and use them consistently. Go read Reg’s post for some great examples. Naturally, your conventions need to be communicated to other members of your team as well as to anyone down the road who might read your code.
An example that occurred to me today has to do with exceptions. When should you throw a standard exception versus a specialized derived class of exception? For instance, if a function within an application accepts an argument that should not be null, should you throw a NullArgumentException? Using thelophanic convention, the answer is “maybe”. It depends on how generic the function is, what the argument means, and under what conditions it might become null. If it’s extremely unlikely that it would ever be null, then maybe you don’t check for null at all and just let whatever runtime exception occur that would be the result of using it as if it weren’t null. When an exception is coughed up from deep inside your framework of choice, that’s a pretty clear signal that something is very wrong and unexpectedly so.
If it’s possible for the client code to inadvertently pass in a null argument, however, then you should throw an exception to let them know exactly what they did wrong. Should it be NullArgumentException, or an application-specific class of exception, though? Again, thelophanic convention asks “what are you trying to say here?” If the client code catches your exception, will it be possible to distinguish this case from any other exception that might occur? In other words, is it possible to generate a NullArgumentException by any other means, thus diluting the meaningfulness of catching that exception? Could the client code want to do something different to handle this specific case? If so, then use an application-specific exception, because the catch block can’t easily distinguish the cases by looking at the traceback. But even if this is the only opportunity for a NullArgumentException, you may still want to throw a more specific exception, depending on the abstraction represented by the function and argument. MyApplication.CustomerMissingException may be more meaningful within a customer maintenance routine that expects a Customer object. On the other hand, if your function operates generically on a wide range of object classes, then NullArgumentException may say all you want to say.
Thelophanic convention is the best idea I’ve encountered so far for how to handle when TIMTOWTDI (There Is More Than One Way To Do It). But I have seen (and used) many other approaches:
- Novices choose the only method that they know about, or the first one they can find.
- Newly established programmers follow a strict religion — whether it’s a company policy, an “industry standard”, or “best practices”.
- Anal-retentive programmers choose the most efficient solution: least code, leanest on resource usage, or fastest.
- Geeks with delusions of grandeur choose the most clever algorithm. After fooling themselves enough times, they move up to…
- Experts choose the most readable version. After rewriting that oh so readable code several times, though…
- Gurus choose the most extensible/maintainable approach. But that’s only one step towards reaching the next level:
- Bodhisatvas choose the thelophanic convention, enlightening themselves and others.
Will there be further stages of enlightenment regarding what to do when TIMTOWTDI? Probably so. But that’s beyond my lights for now.