Code Deliberately

All code should have a purpose. There should be just as much code as necessary to execute your goals and no more.

Unintentional or unnecessary code raises many difficult questions: What is the purpose of this code? Is this code actually important? Did this code ever work?

By contrast, intentional code is easier to read and modify. When you know that every line of code matters, you can trace its logic without distraction and apply modifications in just the right spot.

Case Study

The reason I've been thinking about coding deliberately is due to a recent overhaul of Trello Android websockets.

The old websockets implementation was kind of a mess. I'm sympathetic to how the code got into that state. First, the websocket protocol is tricky. Second, once connected, there's another layer of protocols for communicating with the Trello server. Third, there was no documentation for the Trello socket protocol. And fourth, the initial Android socket implementation was an intern project.

Unfortunately, the end result was that modification to the websocket code was practically impossible.

For starters, it was a pile of spaghetti code that was hard to read. But more importantly, I couldn't be sure it used the correct protocol for communicating with Trello in the first place. Even if I could untangle the existing logic, I wouldn't know whether reproducing it would be the correct thing to do!

The solution was to properly document the protocol. One of the server developers took the time to write it out, then we went back and forth fleshing out the various corner cases. Once the protocol was fully documented, I rewrote the websocket protocol using the correct logic.

Unsurprisingly, in the process of rewriting websockets, I discovered a number of mistakes with how our old sockets functioned. For example, the original websocket code thought that it was regularly missing socket updates and would constantly be re-requesting data from the server. Ouch!

Due to the obfuscation that the gnarly code provided, none of us knew about these issues for years. It was a breeding ground for sneaky bugs.

Strategies

Crafting good, intentional code is difficult. It requires constant vigilance but the payoff is worth it.

Here are a few strategies I use to keep code neat:

  • Before pushing code, do a quick personal code review. You'll be surprised at what you accidentally left behind while developing. It's okay to throw ideas against the wall and see what sticks while prototyping a solution, but you should clear out unused ideas before it becomes part of the permanent record.

  • Always be on the lookout for unnecessary code and remove where possible. If you come across code that makes no sense, try to understand it. Ask yourself (or the coworker who wrote it) for the reason behind the code and remove the it if it is no longer necessary.

  • Document bizarre (but unfortunately necessary) pieces of code that might otherwise be interpreted as unintentional code for future generations.

That said, everyone makes mistakes. Remember to be kind while you work to improve the code.

comments powered by Disqus