Contract by Comment

When you write a class, you are not simply writing a class. You are designing an API for clients of your class. Perhaps this sounds obvious. And when you design an API, it is important to balance power with flexibility, convenience with control. Your interface is your contract.

I saw the following code the other day:

/**...
NOTE: For sale items, the productName MUST end with $S$
*/
public String someMethod(String productName) { ... }

What’s the matter here?

The author of this class is trying to enforce his interface in an extra-programmatic way. He wants us to please not pass anything that doesn’t end with an $S$. But he does not forcibly keep us from so doing.

Note that we are not told what fate befalls those poor saps whose productNames do not end with $S$. The author of this method is Asking "Please honor this programmatic "contract", despite the fact that it’s totally fake, because if you don’t honor it the class will break or, worse, fail silently, or even worse, appear to act correctly while it just silently fails".

This is what I call contract by comment, which is no contract at all. Everyone should know what a phenomenally bad idea this is. In fact, it rather seems that we've heard a butt load of times that we aren't supposed to do this sort of thing. Ever. So what's the real issue here?

The lesson is this: in programming, as in life, and contrary to our social intuition, it is actually more generous to be hardcore. Easygoing people are approachable. They happily give you little bite-size Abba Zabbas from the big plastic sacks they keep hidden in their cubes. Lots of them. They are nice people.

More so, it certainly appears that these easygoing, chirpy folks are "nicer" than the pencil-bending guys at the Monday meeting who are always harping on details, beating the dead horse, foregoing chit-chat about your racquetball club, and not shooting the breeze about how loaded they got in Vegas this weekend.

The water cooler guys seem nicer, if even in a bitchy way. It would appear in fact that we are supposed to become water cooler guys. That the company wants us to gravitate toward the middle, where we loosen our belts after an $8 lunch pasta from Nick’s and complain in a vaguely pained, vaguely self-deprecating, vaguely resentful whine for an extra 15 minutes about how the boss won’t get us tools. Even though they’re 3 million ahead of this quarter last year. The bastards. Ha ha ha. Isn’t it true. Aren’t we collegial.

Guys don’t seem nice who have their heads in their screens all the time. They’re always ranting about "standards". They hate mistakes. They don’t suffer fools gladly. They will argue with you about the implementation because they give a damn about the implementation. I submit that it is these programmers who turn out in the end to be nice. Because it is work. It is your job. It is not a party. It is fun, if you’re doing it right, but given the choice, many of us would be somewhere else any given hour of the work day.

It’s not nice to be nice. It’s nice to be hardcore. Because when you’re hardcore, you’re clear. People know what they are supposed to do. They know how to do it, or know they better find out how.

I don’t know about you, but I don’t like to get a phone call at midnight that I need to come in and fix some broken production app. The hardcore guy’s app doesn’t break, and so he doesn’t get that phone call, or cause others to get those phone calls. I appreciate that. I think it’s nice. Because the attention to detail is there, and because things are dotted and crossed, and because he has been very strict about following the rules and very strict about what he’ll allow and disallow through the firewall, within the cluster, into the method.

In my book, that is the nice guy, because he doesn’t ruin my life. if I wanted to shoot the breeze with somebody, it wouldn’t be Chuck the Analyst down the cube farm who is super nice and didn’t want to hurt the customer’s feelings so they didn’t ask for clarification so we wrote the wrong thing. I don’t think that’s nice to me as the programmer, and it isn’t nice to the customer who’s paying for something they don’t want. If I had to shoot the breeze with someone, it ain’t Chuck. It’s Alison. So if the story here is that we’re going to shoot the breeze with Chatty Kathy from HR, then I’ll just go home. That’s just not a reward for me: I want my stuff to work. And I depend on her. Be hardcore and make your stuff work. People will appreciate your generosity in so doing. If you’re concerned about what others think.

If you’re not so concerned, then ask yourself some pretty tough questions about your API. Make it tough. Make it flexible where it needs to be and convenient where it needs to be, and don’t be mean to your clients by silently failing if they don’t do what you ask.

Disneyland doesn’t ask me nicely to put my seatbelt on, shoot me 1200 feet into the air and hope I don’t fall out. They clamp a big huge steel bar down across me and lock it in place.

Be strict in meetings. Get the work done. Ask the tough questions. It’s nicer.

Be strict in your methods about what params you'll accept, and actually disallow something that's unacceptable. Be a dictator about your upper and lower bounds on a class parameter. Don't hope you get a good deal. Don’t pray that your client’s param ends with $S$. Make sure it does. And if it doesn’t, throw an appropriate exception. If it makes sense, give them a delimited set to choose from that only includes things that end in $S$.

Perhaps an obvious reason that this sort of thing happens, even when we all know we're not supposed to do it, is that it's a lot more work to do things right. In my experience, you pay now or you pay later, and it's always more expensive to pay later. It's more work, and more expense, and more angry users, to fix an app in production. (Something else all programming managers know).

Don’t make a contract by comment. Enforce it programmatically.