Writing Polite Code

I ran across a generally excellent essay by Michael Feathers on what he calls Offensive Coding. The essence of his argument is that if you find yourself frequently writing defensive code (he uses checking for null as an example), the root cause may be that the code you’re working on is called by offensive code. In other words, code that forces you to write defensively.

This resonates with me. Some of my clients have been with me for as long as a decade, so I maintain a heck of a lot of code. Some of it is mine, and some of it is not. I’ve never minded maintenance and refactoring as much as most of my colleagues appear to, but one thing I don’t like about maintaining code is the inordinate amount of time I spend either coding defensively, or doing forensic work to document what the heck is going on so that I don’t have to code defensively.

The opposite of offensive code might be called polite code. And it strikes me that one of the features of polite code is that it’s as self-evident as possible and accurately documented. Good code is self-evident as to the “how” of what it’s doing, and documentation in the form of comments and external documents provides the “why”.

I just spent a couple of hours reverse-engineering some code that handles an automatic product version upgrade because I did not want to risk hosing a production system without being sure about how some items in an application config file were set. I shouldn’t have had to do that, but every reference I could find to these configuration items were vaguely worded and not written with the question in mind, “what will be the concerns of the user reading this”?

That happens a lot … documentation frequently answers questions a user would never ask or give a fig about. It states the obvious, or beats the irrelevant to death, but it never addresses a likely real-world question. To be concrete: the meaning of “InstallMemberRole=true” was I’m sure quite obvious to the original author at the time he was in the throes of creating it. And it seems most likely that this item, in the context of the section of a portal framework configuration most likely means that during the installation process, the member role feature will be installed.

What isn’t ever stated is whether this applies to version upgrades, and if so, whether it will blow away an existing user base. God bless Google, I found some people discussing it who said that it would in fact blow away the existing user base. But, those people may or may not know what they are talking about, and besides, isn’t it odd to default this setting on and thus put people’s user bases at risk? And maybe it involves upgrades to functionality that I’d want to weigh the benefits of.

Well, no matter … with over 1500 impatient active users at stake I can’t afford to guess, so I plowed into the code and tracked down the called T-SQL scripts and made damned sure. This is a defensive action I should not have had to undertake.

As I have said elsewhere, English is a programming language too, and this is another example of why that’s so.