Lessons from Pragmatic Programmer: Stone Soup & Boiled Frog
I am continuing my thoughts of readings from Pragmatic Programmer. Previous article was on: software entropy
I want to share how writing tests, documentation, initial system setup, and technical debt relate to the fables of stone soup and boiled frog.
I go into detail how these concepts relate to the fable and go over ways how to identify you are encountering similar situations.
The article will take you about four minutes to read.
Introduction
This chapter introduces two fables, stone soup & boiled frog. Quick summary of both:
- stone soup fable: by getting everyone to donate items for a “stone soup”, the soup is better for everyone.
- boiled frog fable: a frog when put in a slow pot of boiling water, the frog will keep adjusting to the increasing temperature until well, the frog meets its demise.
As children’s fables, they serve moral lessons. With stone soup, things are better when everyone works together. The boiled frog, well, I never heard that when I was younger.
Stone Soup in Software
Thinking about how the stone soup fable applies to software, I realize there are two areas where the practice of software where everyone contributing improves the individual “stone” contributions:
- Tests
- Documentation
Writing Tests
When everyone writes tests, the system is better than if only one person or specific group writes tests. Testing at the unit level, at the integration level, even the end-to-end system level all makes the system more robust.
There are more check and balances, not only in the “holding everyone accountable” kind, but also in the “edge cases and debugging” kind.
If only one person on the team wrote tests with their code while everyone else just “coded”, the end result of working with the system will be unsatisfactory in the long term.
When everyone writes tests, for their code in the system, the end result of working with the system becomes better than if just one person wrote tests.
Documentation
Another area where everyone contributing is better than alone: documentation.
Not in the sense of “everyone writing” documentation, in the sense of: “everyone using the documentation”.
When everyone uses the same documentation, it is up to date, readers point out errors, authors update with corrections.
The documentation becomes a source of truth for the system and everyone keeps the documentation useful for the system.
Getting Everyone To Contribute
In the fable, it’s almost a bit of “trickery” where the protagonists use the curiosity of others to get them involved in improving the soup with small contributions here and there.
In software, what’s the carrots, celery, meat equivalent?
Sometimes, it take education, either by theory or by experience. Other times, it may take authority or empathy by being hands on.
Every situation is different and would require a different approach.
Boiled Frog in Software
Possible software equivalent of boiled frog situations are when:
- there are lot of “work around” instead of “doing the right thing”
- a new person can spot existing issues right away
- features take longer to deliver
- side-effects of new features are unknown and/or larger
- re-writing/migrating to a new system is becoming a viable option
The “boiling point” is when the business owners lose confidence in the programmer’s ability to manage the system. That’s when the frog meets its demise in software.
The more senior you are as a programmer on your team, you job is to deliver features and maintain things below this boiling point. Problem is, these two things will keep increasing.
Areas I have seen this happen:
- initial system setups
- technical debt
Initial System Setup
When a new member on your team has a weak on-boarding setup of the system they will work on, it may be fine when there are a handful of team members. Or heck, even when there are 10x more team members. The key is:
Setup is fast and just works
When setup is slow, complicated, and fragile, that is a start of a boiled frog situation.
Problem is, this setup problem is not “immediate”.
When a new team member is on-boarding onto the team, they have time and space to setup the system, even if the setup is slow, complicated, and fragile.
The real problem becomes when the same team member has to re-setup the system because:
- migrate to a new machine
- weird behavior that happens locally
- misconfiguration or auto-updates of parts of the system requires down time
The boiled frog effect from a bad system setup really comes into effect in the above, especially with software development systems.
Technical Debt
Another area where boiled frog effects “creeps in” is technical debt taken out when deadlines are near, misjudgements made, or any other reason.
The debt builds and builds over time, until the system has more debt than actual “features”.
Getting out of Hot Water?
In the fable, the boiled frog never does solve the problem for themselves. How to solve for the boiled frog effect in software? Well, in a way to solve for any of these problems is to get everyone to pitch in and solve the problem together.
The problem built up over time by everyone, solving will take time by everyone to make things better.
Best time to plant a tree was twenty years ago, the next best time is now.
Remember, have empathy for past programmers that put the system into the situation.
- They worked their best with the information available at the time.
- They wrote/designed solution for that specific requirement.
- Business requirements always change, especially as things “succeed”!
I believe the best way of getting out of hot water is you have to do it slowly while delivering value. I’m not a subscriber to: “Stop the world and redo it” thinking (anymore.)
At the same time, know when the frog is “over cooked” and move on.
Conclusion
With software, there are areas where the stone soup and boiled frog fables are applicable.
For the boiled frog, I found technical debt and weak system setup to be areas where the fable rings true. With stone soup, documentation and tests are where everyone contributing is better than alone.
Using basic fables to teach larger concepts and map out possible solutions when the current situation matches.