Writing up the design of a software system boosts productivity because it’s much less effort to fix bugs in the design before you write a line of code.
Since John ranted about ranting this week, I almost let out a get-off-my-lawn rant about how the kids these days don’t know about working out a design in writing before coding. Then I remembered that I only know a little bit of everything there is to know, but I am convinced it’s best not to give any energy to anything I don’t want more of.
Of the many subjects I studied years ago when earning my degree in computer science, software engineering persists as the most useful. I can barely recall how to code in Ada or Pascal, but I often return to the principles of discovering requirements, putting software design down on paper and planning for the entire system life cycle. I still keep those textbooks on a shelf in my office. I have a fond feeling about them similar to the one I get from the first edition Dungeon Masters Guide. Something nudges me to crack open those old books because there’s bound to be some wisdom I missed before.
I was thinking about Software Engineering Concepts by Richard Fairley as I read a blog post titled “Waterfall” doesn’t mean what you think it means. That post focuses on the misconceptions of waterfall versus agile. Perhaps the amorphous thing that people call agile enables the neglect of proper documentation. Although, I’ve observed this behavior long before anyone had a fashionable label for their lack of process.
Although I learned of the power of working up a design in writing while in class, the practice proved itself over the years. The argument is simple — it’s much less work to fix a flaw in the design when it’s just words and diagrams. Coding is comparatively more expensive, especially if you must throw away hours of work to start over. This might not be obvious to everyone.
Here’s my understanding of the software engineering process.
- Discover the purpose of the system by writing down stories about how users will interact with it. Write them as non-technical stories that the client can understand.
- Describe the data model, again in plain language. Validate the data model versus the user stories. Possibly add more stories and expand the data model. A data flow diagram can help. Describing operations between the data objects can help.
- Write down any constraints you can think of. Some are obvious, such as when you know you’ll code the system in PHP because it’s the language you’ve been coding in for more than 25 years. Some constraints are standard, such as response times or maximum simultaneous users. Constraints can cause you to discover new user stories or to adjust the data model.
- Describe the most important algorithms, database structures and objects. It isn’t code yet, but you’re thinking about how it would be coded and teasing out problems that might come up as the parts interact. It may cause you to return to any earlier step and revise your thinking, but that’s easy because it’s just words.
- Figure out how you will test the system once it’s complete, otherwise known as a test plan. Figure out how the system will be maintained over time, otherwise known as a maintenance plan.
- Start writing code, including unit tests. Keep validating that the code you’re writing honors the design. Write code that can be tested with the test plan. Write code that can be maintained. Revise the plans if necessary.
- Run the test plan. Hopefully, unit tests were all passing and nothing major pops up that will cause a change in the design.
- Deploy the system and stick to the maintenance plan. If you discover a flaw in any of the previous work, update what you wrote before.
Quite often, I see the above process compressed into a Statement of Work written up by a non-technical client, a list of tasks brainstormed in an hour for the purpose of estimation, and then a lot of churn on closing tasks. It’s easy, like wolfing down a bag of chips. Of course, it can give you indigestion or worse if you go back for seconds or thirds or …
