By Rob Keefer

My first mountain biking trip was with a few friends. I was excited to try out my new bike, which came with extra gear such as front and rear reflectors, a tire-pump, speedometer, and a water bottle. One of the more seasoned riders took one look at my bike and said, “Ok, we need to get this bike ready to ride.” He then proceeded to take everything off! He took off the lights, reflectors, pump, speedometer, and kickstand because they “added unnecessary weight.”

I did take my water bottle with me, though it was the heaviest artifact that could have been removed. The water bottle is a necessity for a good trip, even though the bike functions perfectly fine without it.

We hadn’t been out more than 30 minutes when I fell off the bike so hard that I disengaged the front wheel from the fork of the bike! It was then that I understood why my friend had removed the extra artifacts from my bike. Not only would they have made the bike a little heavier, but they would have broken off anyway.

This short story has a lesson for software developers. A while back, I worked with a colleague to build a system that would enable a factory floor robot controller to communicate with a centralized server. The development of communication systems is often troublesome due to the inherent complexity of message passing. However, I was confident in our plan to use a Test-Driven Development (TDD) approach.

TDD calls for the developer to write tests and solution code simultaneously. It is a proven approach in which the tests serve to document the code and validate that it is correct. This documentation and validation component of TDD encourages practitioners to abandon formal documentation altogether because it can quickly become out of date and never used.

We spent the first day of the project analyzing all the requirements of the system and the messages the robot would send to us. The next day we drew sequence diagrams for all of the messages. Sequence diagrams are a form of formal documentation, leading my co-worker to question the value of this exercise since we were committed to the practice of TDD. He was rightfully concerned that we were wasting time with the sequence diagrams.

One principle of the Harmonics Way is to Embrace Your Complexity and No One Else’s. So, while I advocate for TDD, and believe that the tests provide a solid form of documentation, the sequence diagrams helped me understand a complex system. The documentation served as a tool to help me embrace the complexity of the system through further analysis of the problem. I did not intend to provide formal documentation for future developers.

Software developers are paid to develop software, not write documentation. However, some documentation may provide a useful mechanism for understanding the complexity of a system. It is up to the developers to embrace the complexity required to build a quality system and abandon practices that add overhead or deter them from the goal.

Just as my friend removed many unnecessary components from my mountain bike, software developers should remove any part of their process that doesn’t add value. However, just as I did take a water bottle on the ride, there may be important ingredients of a process that support high-quality development. The goal is to find the balance and try to make sure the process is light and sufficient - barely sufficient.

---