Review: The Enduring Wisdom of The Pragmatic Programmer (20th Anniversary Edition)

---

Review: The Pragmatic Programmer: 20th Anniversary Edition

"The Pragmatic Programmer: From Journeyman to Master" by Dave Thomas and Andrew Hunt was a foundational gift I received after an internship, offering invaluable guidance as I began my career as a professional software engineer. A decade later, a re-read revealed that while its general advice remained robust, references to outdated technologies like CORBA made it feel a bit dated. Recognizing this, the authors released a 20th Anniversary Edition, meticulously updated for modern developers. This new edition features one-third brand-new material covering topics like security and concurrency, with the remaining content extensively rewritten based on their practical experience. This updated version was a topic of lively discussion in my work book club.

This book primarily targets individuals embarking on their professional software engineering journey. While experienced developers might find tips like Tip 28: Always Use Version Control obvious, it also serves as an excellent resource for senior developers mentoring juniors, articulating actionable advice clearly. Furthermore, it benefits those without a formal computer science education by explaining concepts like big-O notation and guiding further learning. I believe any software engineer, regardless of experience, will glean valuable insights, though it truly shines for beginners.

A particularly commendable aspect of the book is how the authors apply its principles not just to software engineering but also to the book's creation itself. Originally written in troff and later converted to LaTeX, they exemplified Tip 29: Write Code That Writes Code by developing a program for this conversion. In the anniversary edition, they recount their efforts to use parallelism to speed up the book's build process, which surprisingly led to bugs.

Perhaps the book's strongest feature is its summary of key points into short, highlighted tips, conveniently attached to a physical card included with the book. This makes remembering and referencing these principles remarkably easy—a feature I believe more managerial and technical books should adopt.

Chapter 1: A Pragmatic Philosophy

This opening chapter delves less into coding specifics and more into the foundational principles a pragmatic programmer follows, emphasizing taking responsibility for one's work. Tip 3: You Have Agency asserts that if you're dissatisfied, you can initiate change or seek a new environment if change isn't forthcoming. To me, the most crucial advice here is Tip 4: Provide Options, Don't Make Lame Excuses. This section underscores accountability for commitments and the necessity of contingency plans. If a commitment isn't met, the focus should be on providing solutions, not fabricating excuses like, "The cat ate my source code."

Software inevitably degrades without maintenance. The authors draw a parallel to "broken windows policing"—the theory that minor neglects encourage larger transgressions. Regardless of the theory's real-world validity, the metaphor aptly applies to software. This leads to Tip 5: Don't Live with Broken Windows: address any software imperfection, however minor, to prevent a culture of neglect. While challenging in projects already riddled with issues, this tip is invaluable for preventing such environments from forming. In my experience, it's effective: a new project at work, where we committed to Git commit hooks for coding standards, fostered a reluctance to compromise quality, making all initial code a strong example to follow.

A pragmatic programmer is a perpetual learner, diversifying knowledge beyond their specialty—a true jack-of-all-trades. Even specialists should continuously invest in a broad knowledge portfolio, including crucial people skills. The "Communicate!" section offers strategies for effective communication, from presentation techniques to timing. As Tip 11: English is Just Another Programming Language suggests, promptly acknowledge emails, even if a full response will come later, to avoid leaving others feeling unheard. Don't hesitate to ask colleagues for help; that's what they're there for. Crucially, integrate documentation into the development process, rather than treating it as an afterthought.

Finally, the book stresses that its principles aren't rigid dogma; judicious tradeoffs are essential for each project. Perfect software is an illusion. Involve users in defining acceptable quality tradeoffs to expedite delivery. After all, waiting a year for perfection means user requirements will likely shift anyway, reinforcing Tip 8: Make Quality a Requirements Issue.

Chapter 2: A Pragmatic Approach

This chapter introduces the "Easier to Change" (ETC) principle, highlighting benefits like isolated concerns for simpler modifications. It explains why the Single Responsibility Principle is useful (changes in requirements affect only one module) and the importance of naming (good names enhance readability). However, ETC is presented as a value, not an absolute rule; for instance, complex code might be an acceptable tradeoff for high-performance requirements.

A related critical acronym for implementing ETC is Tip 15: DRY—Don't Repeat Yourself. DRY simplifies changes by centralizing information. Failure to adhere leads to contradictory data, potential crashes, or silent data corruption. The authors categorize duplication:

• Code Duplication: E.g., repeated case statements instead of a single function.
• Documentation Duplication: Unnecessary comments that become outdated with code changes.
• Data Duplication: Stale cached results.
• Representational Duplication: Inconsistent API formats between client and server, necessitating common specifications like OpenAPI.
• Interdeveloper Duplication: Mitigated by Tip 16: Make It Easy to Reuse; if code is difficult to use, developers will duplicate it.

Closely tied to DRY is Orthogonality: components are orthogonal if changes in one don't affect others. Systems should comprise independent, cooperating modules, each with a single, well-defined purpose, communicating via clear interfaces without relying on shared global data or implementation details. Orthogonal systems simplify testing, allowing more extensive unit testing over end-to-end integration tests.

Initial software projects often face many unknowns, from ambiguous user requirements to library compatibility issues. The solution is Tip 20: Use Tracer Bullets to Find the Target. Like glowing bullets revealing aim, Tracer Bullet Development offers immediate feedback. Build a small, quickly deployable feature using the chosen architecture, then present it to users. It might not be perfect, but this "skeleton" project is easily adjustable, delighting users with early progress and providing an integration platform for future development.

Tracer code differs from prototypes. For the authors, prototypes are disposable learning tools, never intended for production, and don't even have to be code (e.g., UI mock-ups, Post-it architecture). This aligns with Tip 21: Prototype to Learn. In contrast, tracer bullet code is destined for the final application.

The final tip from this chapter I bring up is Tip 18: There Are No Final Decisions. Decisions should be reversible; abstracting database logic, for instance, should make switching between MySQL and PostgreSQL straightforward. Similarly, a well-built architecture should accommodate future shifts, like a web app becoming a mobile app. However, I somewhat disagree with this tip, as it can be taken too far, leading to over-abstracted code with unused configuration options. It's more practical to anticipate reasonable changes and design for flexibility, rather than attempting to cover every conceivable possibility, which can hinder actual development.

Chapter 3: The Basic Tools

This chapter guides developers on maximizing their tools, investing wisely, and approaching debugging effectively. The first piece of advice is Tip 25: Keep Knowledge in Plain Text. This refers to storing configuration or data in human-readable and machine-parseable formats. Plain text safeguards against obsolescence, as parsing it later is always possible, unlike reverse-engineering binary formats. Moreover, its universal compatibility ensures a vast suite of tools can process it. Extending this principle, they advocate mastering a command shell like bash for its composable toolset, which surpasses the limitations of GUIs. Lastly, learning a text processing language such as awk or perl (or Ruby, in the 20th edition) is crucial for advanced text manipulation; the authors themselves used these to automatically highlight source code in their book.

Next, the authors address debugging, a primary daily task for software engineers. Defects stem from various sources, from misunderstood requirements to coding errors. The authors advocate against blame-finding with Tip 29: Fix the Problem, Not the Blame.

They offer several practical debugging tips:

• Tip 30: Don't Panic: In high-pressure situations, take a deep breath. Focus on root causes, not just symptoms, as bugs can originate several layers away from the visible issue.
• The Impossible has Happened: If you think something isn't possible, you're mistaken; it's clearly happening.
• Reproduce It!: Isolate the smallest case that reliably triggers the bug (e.g., specific input data, action sequence) to facilitate tracing.
• Tip 32: Read the Damn Error Message: Self-explanatory.
• The Operating System is Fine: While possible, it's highly unlikely the bug is in battle-tested systems like the Linux kernel or PostgreSQL; assume the problem lies within your code.
• The Binary Chop: Drastically reduce your search space by repeatedly halving the problematic area. For a long stack trace, log values midway. For a regression, binary chop through commits to pinpoint the culprit.
• Use a Debugger and/or Logging Statements: Debuggers allow step-by-step code execution and variable inspection. In environments without debuggers, logging traces variable changes or program progression before crashes.
• Rubber Ducking: Explaining the bug aloud to a colleague or even an inanimate object can help verbalize assumptions and reveal sudden insights.

After solving a bug, a crucial final step is to write a test to prevent its recurrence.

Chapter 4: Pragmatic Paranoia

This chapter opens with Tip 36: You Can't Write Perfect Software. Acknowledging the inevitability of bugs, design flaws, and missing documentation, the chapter focuses on designing with this reality in mind.

The first concept proposed is Design By Contract, analogous to legal agreements. It defines a function or module's rights and responsibilities through three parts:

• Preconditions: What must be true when the function is called (e.g., valid inputs).
• Postconditions: What will be true upon completion (e.g., a sorted array from a sort routine).
• Invariants: Conditions always true from the caller's perspective, holding at the beginning and end of the call (e.g., a sort routine maintains the original item count). If a contract is violated, the specified action (e.g., crash, exception) should occur.

While some languages like Clojure offer built-in contract semantics, in others, Tip 39: Use Assertions to Prevent the Impossible can implement contracts by asserting conditions. If uncertain how to handle a contract violation, the authors recommend Tip 38: Crash Early. Crashing is preferable to corrupting data, as "dead programs tell no lies." However, ensure resources are properly closed before exiting.

The final "paranoid" tip is Tip 43: Avoid Fortune-Telling. Pragmatic programmers focus on decisions with immediate feedback. The more predictions made about the future, the higher the likelihood of incorrect decisions based on faulty foresight. This "fortune-telling" often occurs when:

• Estimating completion dates months in advance.
• Planning designs for future maintenance or extensibility.
• Guessing future user needs or technological availability.

Chapter 5: Bend, or Break

Building on the concept of reversible and easily changeable decisions from a previous chapter, this section delves into implementing flexibility in code. The core idea is to create code that "bends" to circumstances rather than "breaks." This largely involves decoupling code, which refers to reducing shared dependencies. Coupling can range from simple shared global variables to complex inheritance chains.

The authors strongly advise against "Train Wrecks"—long chains of method calls—illustrating with an example:

public void applyDiscount(customer, order_id, discount) {
	totals = customer
			  .orders
			  .find(order_id)
			  .getTotals();

	totals.grandTotal = totals.grandTotal - discount;
	totals.discount = discount;
}

This code traverses multiple abstraction levels, creating tight coupling. Changes at any level (e.g., how customer exposes orders) risk breaking the code. Furthermore, business rule changes (e.g., a 40% maximum discount) could be violated if other modules modify the totals object directly. The authors suggest refactoring to a more encapsulated approach:

public void applyDiscount(customer, order_id, discount) {
	customer
	.findOrder(order_id)
	.applyDiscount(discount);
}

They recommend using only one dot (.) when accessing elements likely to change (e.g., application internals, fast-moving external APIs), even using intermediate variables. However, this rule does not apply to stable elements like core language APIs (e.g., people.sort_by {|person| person.age }.first(10).map {| person | person.name } is acceptable).

Globally accessible data is another source of coupling, complicating program state reasoning as any module can alter it. This includes singletons and external resources like databases. If global data is unavoidable, the key is to manage it through a well-defined, controlled API, rather than direct access. This embodies Tip 48: If It's Important Enough to Be Global, Wrap It in an API.

Poor inheritance use is a third coupling source. While used for code reuse and type modeling, inheritance falls short. Child classes and their users become coupled to ancestors, leading to unexpected breaks if an ancestor's API changes. It also fails for type modeling; class hierarchies quickly become unwieldy, and multiple inheritance (needed for complex types like a Car being a Vehicle, Asset, and InsuredItem) isn't widely supported. Instead of the "inheritance tax," the authors suggest:

• Interfaces/Protocols: Code-free classes defining behaviors. A class implementing an interface promises to define these behaviors, offering a flexible way to achieve polymorphism.
• Delegation: A "has-a" relationship where a class includes an instance of another class to reuse its behavior, wrapping its API in controlled code.
• Mixins/Traits: Sets of functions "mixed into" a class to add common functionality without inheritance. (The reviewer notes uncertainty about mixin implementation in Java-like languages and their distinction from multiple inheritance).

Tip 55: Parameterize Your App Using External Configuration: Values that change during runtime, such as third-party credentials, should be externalized, not hardcoded. Storing credentials in source code is a significant security risk. While flat files or database tables are common, for highly-available applications, the authors propose configuration-as-a-service. This approach allows multiple applications to share configuration, enforces access control, provides a UI for easy editing, and enables applications to subscribe to configuration items for real-time updates without restarts.

Chapter 6: Concurrency

This chapter differentiates Parallelism (code running simultaneously) from Concurrency (things appearing to run simultaneously). In reality, applications are asynchronous, with user input, network calls, and screen redrawing happening concurrently. Serial execution makes applications feel sluggish.

Tip 56: Analyze Workflow to Improve Concurrency encourages breaking temporal coupling (where event A must precede event B). Developers should analyze workflows for opportunities to execute activities concurrently, especially time-consuming ones that allow other tasks to proceed. For instance, multiple independent API calls to a remote service should run on separate threads then aggregate results. If work can be split into independent units, leverage multiple CPU cores for parallel execution.

However, parallelism has its pitfalls. Consider incrementing an integer: if two processes read it simultaneously, both might increment it to n+1 instead of the desired n+2. Updates require atomicity, achieved through synchronized methods, semaphores, or resource locking. These, too, carry risks like deadlocking. The authors strongly advise avoiding shared state where possible, encapsulated in Tip 57: Shared State Is Incorrect State.

The authors encountered this issue while parallelizing the 20th anniversary edition's build process, leading to random failures. The root cause was temporary directory changes in subtasks; new threads, expecting the root directory, would break the build depending on timing. This experience inspired Tip 58: Random Failures Are Often Concurrency Issues.

Chapter 7: While You Are Coding

This chapter is a diverse collection covering psychology, Big-O notation, refactoring, security, and testing.

Tip 61: Listen to Your Inner Lizard encourages heeding instincts. If coding feels difficult, it might signal a flawed structure, design, or incomplete understanding of requirements. In such cases, stepping back—perhaps for a walk or sleep—can often reveal the solution.

Sometimes, instead of writing more code, refactoring is needed. Tip 65: Refactor Early, Refactor Often advocates refactoring as a continuous process. Address any code issues like DRY violations, outdated knowledge, or non-orthogonal designs promptly. Crucially, before refactoring, ensure a robust suite of unit tests exists, and run them frequently to catch regressions.

Regarding tests, the authors make a bold statement: Tip 67: Testing Is Not About Finding Bugs. Instead, tests serve as "the First User of Your Code," providing immediate feedback and forcing developers to define "correct." They also aid good design, as tightly coupled code is difficult to test. The authors caution against full Test Driven Development, fearing it can lead to developers becoming "slaves to writing tests," citing an example of a TDD advocate who spent so much time on tests for a Sudoku solver that the solver itself was never written.

In a sidebar, Dave Thomas recounted stopping writing tests for several months, noting "not a lot" happened; code quality didn't drop, and bugs weren't introduced. His code remained testable, just untested. Andy Hunt, however, worried this sidebar would tempt inexperienced developers to skip testing. My compromise: yes, write tests. But after 30 years of experience, feel free to experiment to understand their precise benefits for you.

Chapter 8: Before the Project

This chapter focuses on initiating projects successfully, beginning with requirements gathering—often termed "The Requirements Pit." Requirements are not readily apparent because, as Tip 75: No One Knows Exactly What They Want highlights, clients often have ambiguous needs. The authors liken requirements gathering to therapy, where an initial request is probed with detailed questions to pinpoint exact needs. They illustrate with a simple requirement: "Shipping should be free on all orders costing $50 or more." This immediately raises questions: Does this include the shipping cost itself? Tax? Ebooks? The programmer's role, according to Tip 76: Programmers Help People Understand What They Want, is to uncover and document such edge cases the client might overlook. This doesn't mean extensive, unread specifications; instead, requirements should fit on an index card. This approach curbs feature creep, as clients visualize the impact of new requirements on the schedule, promoting prioritization.

Projects also come with constraints. A software engineer's job is to evaluate whether these are actual limitations or merely assumptions. Tip 81: Don't Think Outside the Box—Find the Box encourages identifying the true boundaries of the problem. What seems like a constraint might just be a preconceived notion.

Another advocated tip is Tip 78: Work with a User to Think Like a User. If building an inventory system, spend days in the warehouse to grasp processes and system usage. Without this understanding, you might create a system that meets all requirements but is functionally useless. They cite an example of a digital sound mixing board that was technically capable but unusable because it ignored recording engineers' familiarity with tactile sliders and knobs, burying features in unintuitive menus. It did what was required, but not how it was required.

This chapter also re-evaluates Agile methodologies. Many seek "Agile-in-a-Box" solutions, but no process alone makes a team agile. The core of Agile, as per its manifesto, is "Individuals and interactions over processes and tools." For the authors, Agile boils down to:

1. Work out where you are.
2. Take the smallest meaningful step towards your goal.
3. Evaluate the outcome and fix any issues. Applying this iteratively across all levels, from process to code, truly embodies the Agile spirit.

Chapter 9: Pragmatic Projects

This final chapter explores applying "The Pragmatic Programmer"'s lessons to teams. Many principles echo earlier discussions and remain equally relevant at the team level.

The authors advise Tip 87: Do What Works, Not What's Fashionable. Just because tech giants like Google or Facebook adopt a particular process doesn't guarantee its suitability for your team. The way to determine effectiveness is to try it. Pilot new ideas with small teams, observing what succeeds and what fails. The ultimate goal isn't merely "doing Scrum" or "being Agile," but continuously delivering working software. Any new adoption should aim to improve continuous deployment. If deployments are measured in months, strive for weeks; then, target one-week iterations.

Related to continuous delivery is Tip 96: Delight Users, Don't Just Deliver Code. Simply delivering functional software on time only meets expectations, it doesn't delight. The authors suggest asking users: "How will you know that we've all been successful a month (or a year) after this project is done?" The answers might surprise you and extend beyond initial requirements, perhaps focusing on customer retention for a recommendations engine. Once the true measure of success is identified, the aim should be to not just meet, but exceed that goal.

Finally, the book encourages taking pride in one's craft, culminating in Tip 97: Sign Your Work.

Final Thoughts

This review only scratches the surface of this remarkable book. I highly recommend "The Pragmatic Programmer: 20th Anniversary Edition" to every software engineer, especially those new to the field. It makes an excellent graduation gift for anyone completing a Computer Science degree.