I had an interesting experience at work this evening. It was late afternoon, and I was tasked with a somewhat important feature, the details of which were not so clear to me. There was significant work involved in both back-end and front-end, including the database. I have been procrastinating on this for almost an hour.

Normally, I just buckle down and start coding. I have found that once I start coding, it usually gets better, pretty quickly. If I can just ignore the distractions around me, it doesn’t take me very long to reach the cherished flow state, where you are so engrossed in the task at hand, you literally lose the sense of time.

However, this was a hairy feature. There were a few uncertainties involved and I had to go back and forth with more senior developers to smooth out some rough edges. I was still not a hundred percent confident to implement the complete feature on my own. So instead of diving into code, I opened a text file and started writing a detailed specification.

It took me some time to come up with specific requirements for the feature. But as I wrote them down, I noticed the feature getting sharper in my mind. By the time I finished writing the spec, I had a pretty good idea of what the feature was supposed to do, and had a good plan for implementing it.

Once I had the specification, I opened visual studio and started writing code. And then an amazing thing happened. It felt like I had a clear path in front of me. My mind was clear, and my fingers were just spewing out lines and lines of code. Though my original estimate was at least a day, I was able to implement the whole feature in under 2 hours.

Hardcore agile developers usually tend to avoid detailed specs in favor of writing code, and I will admit that I haven’t followed spec-driven development rigorously. However, I have found the benefits of having a specification are huge, and any time spent writing a spec is time well invested, and ultimately saves a lot of time during development.

The reason for writing a spec is not to come up with a perfect requirements document to solve as many problems as you can in advance. The real reason is to solve as many problems as you possibly can in advance to minimize the number of surprizes when you are actually writing the code.

A lot of times, when I write the requirements for a feature, it saves me significant headaches later on during the development stage. Almost all the time, when I dive head-first into code without having a specification at hand, I write lower quality code. The act of writing a detailed specification forces you to think about the design of the program. That helps in narrowing down the scope, fishing out the edge cases, and sharpening the functionality in your mind. That ultimately improves the design of the software.

Once you write a specification, you can revisit it later, only to discover bugs and potential enhancements. It can also serve as documentation, not only for you as a developer, but also for the QA department, when they are testing the functionality. It can be used as release documentation by technical writers. Managers can use it so they can communicate with upper management. Ultimately, a detailed specification benefits everyone.

As I write this, I have decided to be more disciplined and write a detailed specification for most, if not all the features I work on.