Specs First

I’m just about done with the Mythical Man Month by Frederick Brooks Jr. The influence of archaic patriarchal norms are present in more than just the title, but it was a good read. I hope to read more books like this where the point is learning how to write/compose/build software projects rather just how to write software. Many of us have proudly looked on the results of various “Hello World” outputs and then wondered…what do I do now?

For personal projects I often get an idea, open an editor and start coding. I revise often as I go along and then start to make far reaching decisions on how the code is organized, what 3rd parties to use and how to test my code (if I write tests at all). Then I take a look around at my work and see that I’ve painted myself into a corner. I realize the code isn’t going to do quite what I want it to and to get it right amounts to pretty much starting from scratch (git makes this not quite as bad, but it’s still trouble).

Who cares right? It’s just a dumb project that no one will ever see so what does it matter if it doesn’t work? But the project, humble though it may be, still represents effort and the effort is wasted. I probably did learn some things about some bit of tech, but I also re-enforced the habit of writing code too soon. I need to look before I leap and all that kind of thing. Think more, write less. Or at least write words, not code.

Which brings me to Chapter 6: Passing the Word. This chapter is all about documentation. The thing that so many developers (myself included) choose to skip over time and time again…

  • “It’s obvious what it does!”
  • “My code is self documenting!

But it’s not. It is just yet another way to code one’s self into yet another corner or to build something that does see the light of day and then breaks everytime it is modified.

Mr. Brooks tells us that we need not one but two written specifications:

  • One needs both a formal definition of a design, for precision, and a prose definition for comprehensibility.
  • One of the formal and prose definitions must be standard, and the other deriviative. Either definition can serve in either role.

The prose specification was usually what I was missing. I’ve seen plenty of user stories but they all have this bland, “As a user I should be able to select…” and it just bores me to tears. But a document that was more than just a user story, something that actually just talked about what the project was supposed to do, that was new to me.

It’s not a swagger document or a REST API document, it’s just a few(many) paragraphs that describe what the thing should do when it’s done. I wrote a prose specification for a user managment project that I’ve wanted to work on for years. After completing that (and making numerous changes that should save me trouble later) I wrote what I’ll call a technical specification where I actually talk about functions, agruments and parameters. It was way easier to write the technical part after I had written the prose part.

So we will see where this goes. As long as I don’t abandon this endeavour, it should at the very least be amusing.

User management project can be found here.