As I continue my journey to become a better software craftsman, two insights from Martin Fowler and Uncle Bob stand out:
Martin Fowler (Refactoring)
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."
Code is a shared language. Polishing interfaces, refining layout, and writing clear comments make our intent obvious and our logic approachable.
Uncle Bob (Clean Code)
"The only valid measurement of code quality is how easily it can be understood and changed."
Clean code isn’t just functional, it’s adaptable. Applying PPP, auditing variables, and keeping routines focused all strengthen a codebase.
Their principles echo McConnell’s advice, writing code is half the job; crafting clear, human-friendly software is what makes us true craftsmen.
In 2023, shortly after joining Savannah Informatics, I had one of those pivotal moments in my software engineering journey. We were in a review session where an RFC Stephen Mwangi, my tech lead at the time, and I had worked on, and arguably the best I’ve ever had, was being examined by Dr. Ngure Nyanga. During the review, Dr. Ngure mentioned the importance of applying the Pseudocode Programming Process (PPP) in our workflow.
I remember sitting there, nodding along, but deep down, I had to admit, I didn’t know what PPP meant in practice. This was surprising even to me because I had read "Code Complete" by Steve McConnell, a book hailed as a software development classic. That review was the spark I needed. Determined to understand it better, I revisited the book with fresh eyes.
Fast forward a few years into my engineering career, with more real-world experience under my belt, I read "Code Complete" again. This time, the insights felt even sharper, almost pristine, as if McConnell had written them specifically for the problems I was facing in day-to-day development.
The Beauty of Cleaning Up Code "Leftovers"
One concept that stuck with me is McConnell’s section on "Cleaning Up Leftovers." He explains that finishing a feature or routine isn’t just about making it work; it’s about polishing it so it meets the highest standards of quality. He outlines a series of checks that serve as a final pass over your code, almost like a craftsman sanding and refining their work until it gleams.
Here are the key takeaways, simplified and rephrased:
1. Validate the Routine’s Interface
Make sure your routine handles all expected inputs and outputs correctly. Every parameter should serve a purpose. Nothing unused should sneak in, and nothing vital should be missing. It’s amazing how often overlooked parameters become silent bugs waiting to happen.
2. Confirm Design Quality
Ask yourself:
(a) Does this routine do one thing and do it well?
(b) Is it loosely coupled to the rest of the codebase?
(c) Is it built defensively, ready to handle edge cases gracefully?
If the answer isn’t a clear “yes,” it’s time to refactor.
3. Audit Your Variables
Look closely at variable names. Are they clear and descriptive, or cryptic and misleading? Check for unused objects, improper initialization, or anything that might confuse the next person (or future you). Clean variable hygiene leads to maintainable code.
4. Scrutinize Logic and Flow
This is where you catch the tricky stuff, off-by-one errors, infinite loops, improper nesting, or resource leaks. These logical gremlins often hide in plain sight until you zoom in on the structure.
5. Refine Layout and Readability
White space isn’t wasted space; it’s a tool. Well-placed line breaks and clear formatting make your code instantly more approachable. A properly laid-out routine guides the reader naturally through its flow.
6. Align Comments with Reality
Code evolves, and comments can become outdated. McConnell suggests reviewing the pseudocode (or design comments) that guided the implementation. Are they still accurate? Do they clearly explain why a block of code exists, not just what it does?
And here’s the kicker, if a comment simply repeats what the code says in plain sight, delete it. Redundant comments add clutter rather than clarity.
Why This Still Matters Today
Re-reading this section years later reminded me that writing code is only half the job. The other half is communication with our future selves, our teammates, and even the systems we build upon. The Pseudocode Programming Process (PPP) emphasizes thinking before coding, structuring logic in plain language first, and then translating it into clean, expressive code.
This approach not only prevents messy logic but also forces you to think about clarity from the very start. It’s a mindset shift, from “get it done” to “get it done right.”
In hindsight, that review session with Dr. Ngure was more than just feedback on an RFC; it was a reminder of what separates good engineers from great ones.
Great engineers don’t just write code that works; they leave behind code that’s readable, maintainable, and self-explanatory.
The next time you finish coding a feature, don’t stop at “it runs.” Walk through McConnell’s cleanup steps. Check your interfaces, audit your variables, refine your layout, and align your comments. You’ll be surprised how often that final polish transforms good code into truly excellent code.
Top comments (0)