The Merits Of Comment-Driven Development As Counterweight To TDD | Hackaday

Skip to content

The world of software has seen many paradigms come and go, all of which were supposed to revolutionize its development. Still, one of the basic tenets in engineering of there being no shortcuts to just doing the work properly also rings true in the field of software engineering: trying to skip ‘nice to haves’ like proper documentation, code formatting, and proper testing inevitably results in developers nervously trying to ignore the looming avalanche of technical and other project debts as they keep piling up.

While Test-Driven Development (TDD) once got praised as the silver bullet, the principle of writing tests before writing code merely postpones the inevitable project collapse. The elephant in the room is that you cannot pass on the basics in engineering and expect to come out fine on the other end. There’s a reason why phrases like "all tests green, successfully failed in production" have become common.

This is where the concept of Comment-Driven Development (CDD) comes into play. What started as a bit of a joke many years ago stuck in my mind and led me to my current approach in software development that tries to effectively mirror solid engineering principles.

Defining Comments

In the field of software engineering, code comments are often regarded as a bit of an unloved stepchild. No developer regards them in the same way, few appreciate them, most neglect them and some outright banish them from their lives. The most extreme response here is probably that of the Clean Code movement, who together with the Self-Documenting Code crowd insist that inline comments in particular are unnecessary, an eyesore and that beautiful, well-written code documents itself.

Then there are those who use comments as a (temporary) crutch, as in what is referred to as ‘comment programming‘.  This puts comments in the place where code is supposed to go, for either later replacement or to elucidate a specific aspect. None of this uses comments consistently to provide a parallel flow with the code that explains the what, why and how of said code.

Why this matters is that despite claims to the contrary, reading and understanding code is hard. Grasping architectural decisions and intuitively separating them from quick hacks is hard even if you’re reading back your own code after a few development cycles. This is also basically why writing documentation based on just code with at most spotty inline commentary is a nightmare at best.

After working with a variety of (commercial) codebases over the years that were practically dripping technical debt and regrets – as well as writing comprehensive documentation for some of them – I have become convinced that comments are ultimately the Alpha and Omega of a healthy codebase and up to date documentation.

Software Engineering

https://commons.wikimedia.org/wiki/File:Millennium_Tower_adding_pile_section_1.agr.jpg<br>" data-image-caption="Hot-patching the Millennium Tower in 2022. (Credit: ArnoldReinhold, Wikimedia)<br>" data-large-file="https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?w=469" class="size-medium wp-image-1116924" src="https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?w=300" alt="Hot-patching the Millennium Tower in 2022. (Credit: ArnoldReinhold, Wikimedia)" width="300" height="400" srcset="https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg 3024w, https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?resize=188,250 188w, https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?resize=300,400 300w, https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?resize=469,625 469w, https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?resize=1152,1536 1152w, https://hackaday.com/wp-content/uploads/2026/06/Millennium_Tower_adding_pile_section_1.agr_.jpg?resize=1536,2048 1536w" sizes="(max-width: 300px) 100vw, 300px" />Hot-patching the Millennium Tower in 2022. (Credit: ArnoldReinhold, Wikimedia)<br>Although most people see the finished product of engineering and believe that that’s all there’s to it, the truth is that before that bridge, high-rise building or even some fancy electronic widget sees the light of day, most of the work has already happened. Building it is then theoretically as easy as following the provided instructions.

An essential point here is the assumption that said instructions are half-way correct and you don’t end up building your very own Millennium Tower.

Thus the process of engineering begins with the list of requirements. These have to be chiseled into the hardest of stone, as any change here will have potentially massive repercussions. From these requirements you...