Joking Aside
Anybody who knows me will tell you that I find it hard to pass
up an opportunity to make a bad joke, but even I
have learned that there's a time and a place for humour and
writing source code is not it. Programmers spend most of their time
working with and thinking about language, so it's only natural
that they find plenty of opportunity to sneak puns and other word
play into source code. But jokes in source code are a minefield for
programmers who have to maintain the code. Every joke, by its very
nature, confuses the reader and slows down maintenance work.
A long time ago I wrote some marshalling/demarshalling code for a middleware platform. I made the mistake of leaving a groanworthy pun in the source code which caused much lack of merriment when rediscovered.
A bit of background on marshalling: data sent between machines of different endianness must be byte swapped during communication. In some protocols, data is always sent in "network byte order", traditionally big endian, which is inefficient when the sender and receiver both have the opposite byte order. A better scheme is for the sender to include a field in the header that indicates the endianness of the following data. The sender does not have to byte swap outgoing data at all and the receiver must only byte swap incoming data if the endianness of the data is different than its native endianness.
Some systems, CORBA for example, compile the middleware libraries to know their endianness and send a boolean flag indicating big-endian or little-endian. Because we were planning to port the system to different architectures, I didn't want maintain the endian flag for each architecture -- that sounded like too much manual work. Instead, my protocol used a 2-byte field in the header of each message. The sender set the field to a well-known numeric value, each byte of which was different. The receiver checked the received value of the field against the well-known value. If they were different, the the data needed to be byte swapped.
I called the header field 'elvis' and used 57005 for the well-known numeric value. Why? Because the code that detected the byte order then looked like this:
void receive( Message message ) {
short elvis = message.readShort();
if( elvis != 0xDEAD ) {
message.setByteSwapped(true);
}
...
}
HAHAHAHA hahaha ... ha ha ... ha ... ha? ... err... maybe you had to be there.
Amusing or not, the joke makes the code far too hard to understand. I should have written it like this:
static final short LOCAL_BYTE_ORDER = 0x1234;
...
void receive( Message message ) {
short messageByteOrder = message.readShort();
if( messageByteOrder != LOCAL_BYTE_ORDER ) {
message.setByteSwapped(true);
}
...
}
The difference is obvious. It may be less amusing to the programmer writing the code but, more importantly, it is less infuriating for the programmer maintaining the code.