The Essence of Comedy, and Good Comments, is Surprise

I've heard it said that surprise is the essence of comedy. A funny moment is funny because of its unexpected nature. This is surely only part of the equation. But it gets you a long way.

A good idea to keep in mind, when writing code is: "is this surprising?". If so — add a comment. You do not want code to be funny.

The hard part about programming tends to be the exceptions. The corner cases. That which is unforseeable to mere mortals. An irregularity in high-dimensional configuration space has to beget an irregularity in the code to process it. Understanding this irregularity, and then replicating all of its mishapen form in code, tends to be the locus of most programming effort.

The natural reaction of the reader to these irregularities is surprise. The goal of the writer, then, is assuaging this surprise. An explanation of the reason for the surprise; for the struggle that went in to creating it.

If the irregularity is not commented, the natural question is — "why the irregularity?". Is it correct? Is it intended? Does this region of higher entropy correspond to something real outside of itself? Or is it mere accident, oversight, or historical artifact?

Of course, reality is high-dimensional, and reducing even one tiny corner of it to a single rule is, more times than not, fraught with difficulty. "The only rule is that there are no rules". But I daresay that this single rule is the highest alpha amongst similar such rules.