Introduction

If you have been programming for a while, you have already noticed that writing code is only half the job. The other half is dealing with changes, bugs, crazy deadlines and that colleague who thinks everything can be solved with an if. Well, The Pragmatic Programmer, written by Andrew Hunt and David Thomas, is the book that does not teach you a language — it teaches you to think like a true professional.

Originally published in 1999 and updated in 2019 in the 20th anniversary edition, the book remains absurdly relevant because it focuses on timeless principles of software engineering: responsibility, automation, communication, adaptability and critical thinking. These are lessons that apply to any language, framework or paradigm — from Python to Rust, from monoliths to microservices.

In this article, I comment on the points that struck me the most while reading, with practical examples in Python and tips you can apply in your daily work today. This content is aimed at developers of all levels who want to grow beyond code and build a truly pragmatic mindset. If you want to be more efficient, more reliable and more respected on your team, keep reading.


Own Your Code

No more “oh, that is not my part”. If something is broken and you can help, help. The book insists a lot on responsibility: code is like a house — if you see a leak, you do not pretend you did not see it. You fix it or call someone who knows how.

This concept is directly linked to the broken windows metaphor (broken windows theory): a broken window left unrepaired signals that nobody cares, and soon the rest of the building starts to degrade. In code, a badly named function, an ignored duplication or a forgotten TODO work the same way.

Practical example: if you find a function with duplicated logic during a code review, do not ignore it. Open a PR to refactor it. Small continuous improvements prevent gigantic technical debt.

💡 Tip: Adopt the boy scout rule: “Leave the code cleaner than you found it”. You do not need to refactor the entire project — fix a badly named variable, remove an unused import, improve a comment.


DRY — Don’t Repeat Yourself

Repeating code is like copying and pasting a problem. Every time you duplicate logic, you are creating a time bomb: when you need to fix a bug, you will have to remember every place where that logic was replicated. Want to keep your sanity? Centralize knowledge.

The DRY principle is not limited to code — it applies to documentation, configuration and even processes. If a piece of information exists in two places, eventually they will diverge.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Before: validation duplicated in several places
def processar_pedido(pedido):
    if not pedido.get("cliente_id"):
        raise ValueError("cliente_id is required")
    if pedido.get("total") <= 0:
        raise ValueError("invalid total")
    # ... processing logic

def exportar_pedido(pedido):
    if not pedido.get("cliente_id"):
        raise ValueError("cliente_id is required")
    if pedido.get("total") <= 0:
        raise ValueError("invalid total")
    # ... export logic
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# After: a single centralized validation function
def valida_pedido(pedido: dict) -> None:
    """Validates the required fields of the order."""
    if not pedido.get("cliente_id"):
        raise ValueError("cliente_id is required")
    if pedido.get("total", 0) <= 0:
        raise ValueError("invalid total")

def processar_pedido(pedido):
    valida_pedido(pedido)
    # ... processing logic

def exportar_pedido(pedido):
    valida_pedido(pedido)
    # ... export logic

⚠️ Warning: DRY is not about eliminating every visual repetition in code. Two functions can have the same structure yet represent different concepts. The principle is about not duplicating knowledge — if the validation rule changes, changing a single place should be enough.


Think in Abstractions, Not Details

The book talks about orthogonality: well-designed systems have independent parts. If you touch one thing and break another, your design is screaming for help. Orthogonal components can be modified, tested and replaced without unexpected side effects.

In practice, this means separating responsibilities clearly. A parsing module should not know how data is persisted. A validation layer should not depend on the web framework being used.

How to apply orthogonality

  • Separate parsing, validation and persistence into different modules.
  • Use clear interfaces between layers — explicit parameters, typed returns.
  • Avoid global variables and unnecessary shared state.
  • Prefer composition over deep inheritance.

This approach closely resembles the principles discussed in BFF architectures, where layer separation is fundamental to keeping security and maintainability.


Tools Are Your Friends

Automate everything you can. Scripts, tests, deploy, formatting, linting. If you do something manually more than twice, you are asking for mistakes. The pragmatic programmer invests time in building tools that save time in the future.

A great starting point is creating a Makefile to automate common tasks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Makefile for everyday tasks
.PHONY: setup test lint format clean

PYTHON := python3
VENV := .venv
ACTIVATE := . $(VENV)/bin/activate

setup:
	$(PYTHON) -m venv $(VENV)
	$(ACTIVATE) && pip install -r requirements.txt

test:
	$(ACTIVATE) && pytest -q

lint:
	$(ACTIVATE) && flake8 .

format:
	$(ACTIVATE) && black .

clean:
	rm -rf $(VENV) __pycache__ .pytest_cache

Now, instead of remembering commands, all you need is:

1
2
3
4
make setup   # sets up the environment
make test    # runs tests
make lint    # checks style
make format  # formats code automatically

ℹ️ Info: Besides the Makefile, explore tools such as pre-commit to automate Git hooks, and tox to test against multiple Python versions. The goal is for the quality process to run automatically, without depending on individual discipline.


Communication Matters (A Lot)

It does not help to be a code ninja if nobody understands what you do. The book dedicates an entire chapter to communication — and it is not about generic soft skills, it is about effective technical communication: document decisions, explain trade-offs, share context.

A powerful tool for this is ADRs (Architecture Decision Records) — short documents that record what was decided, why, and which alternatives were considered.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# ADR-0001: Chosen database

## Context
We need a relational database with support for semi-structured JSON
for the product catalog module.

## Decision
Use PostgreSQL 16 for native JSONB support, ACID transactions
and extensibility (e.g., pg_trgm for full-text search).

## Alternatives considered
- MySQL 8: good support, but less mature JSONB.
- MongoDB: schema-less, but we lose multi-document ACID transactions.

## Consequences
- The team needs familiarity with PostgreSQL.
- Migrations managed via Alembic.

📌 Example: ADRs are especially useful in teams that grow fast. Six months later, when someone asks “why PostgreSQL and not MongoDB?”, the answer is documented — it does not depend on the memory of whoever was in the meeting.


Adapt and Keep Learning

Technology changes fast. Today it is Python, tomorrow it may be Rust. The pragmatic programmer does not cling to the language, but to the principles. Whoever masters concepts such as design patterns, automated tests and clean architecture moves between technologies with ease.

The book suggests regularly investing in what the authors call a knowledge portfolio — just like a financial portfolio, it needs diversification and regular contributions.

How to invest in your knowledge portfolio

  • Set aside time to study something new every month: a language, a framework or a concept such as TDD.
  • Read other people’s code — open-source projects are a free school.
  • Join communities — meetups, forums, conferences (even online).
  • Teach — explaining a concept is the best way to really understand it.

Test Everything (But Intelligently)

It is not just about writing unit tests. Think about integration tests, property tests and automation. The pragmatic programmer tests as a defense, not as bureaucracy — every test must have a clear purpose.

A powerful approach is property-based testing with the Hypothesis library for Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from hypothesis import given, strategies as st

def soma(a: int, b: int) -> int:
    """Adds two integers."""
    return a + b

@given(st.integers(min_value=0), st.integers(min_value=0))
def test_soma_inteiros_positivos(a, b):
    """The sum of two positives must be >= either of them."""
    resultado = soma(a, b)
    assert resultado >= a
    assert resultado >= b

Unlike traditional tests where you define fixed inputs, Hypothesis generates hundreds of random inputs and automatically looks for edge cases. This finds bugs that manual tests would rarely catch.

💡 Tip: Combine unit tests (fast, isolated) with integration tests (real scenarios) and property-based testing (automatic input exploration). Each layer covers different failures.


Feature Toggles for Safe Changes

Want to ship a feature without breaking everything? Use feature toggles (feature flags). They let new code exist in production but only be enabled for a controlled group — or disabled instantly if something goes wrong.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import os

# Feature toggle via environment variable
FEATURE_NOVA_PRECIFICACAO = os.getenv("FEATURE_NOVA_PRECIFICACAO", "0") == "1"

def calcula_total(pedido: dict) -> float:
    """Calculates the order total using the active version of the algorithm."""
    if FEATURE_NOVA_PRECIFICACAO:
        return calcula_total_v2(pedido)  # new algorithm
    return calcula_total_v1(pedido)      # current algorithm (stable)

This technique is essential in continuous deployment environments — you deploy at any time, but control when a feature is enabled. Systems such as LaunchDarkly and Unleash offer advanced toggle management, but environment variables already solve simple scenarios.


Reproducible Environments

No more “it works on my machine”. Use Docker and .env to ensure that the development, test and production environments are identical. As I showed in how differences between terminal and pipeline cause bugs, environment reproducibility is the first step to eliminating failures.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# Dockerfile for a Python application
FROM python:3.12-slim

# Image metadata
LABEL maintainer="Lincoln Zocateli"
LABEL description="Reproducible environment for a Python application"

WORKDIR /app

# Install dependencies first (better layer caching)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Default command
CMD ["python", "app.py"]
1
2
3
# Build and run
docker build -t minhaapp:dev .
docker run --env-file .env -p 8000:8000 minhaapp:dev

⚠️ Warning: Never put secrets (passwords, tokens, API keys) directly in the Dockerfile or in the code. Use .env files that are in .gitignore, CI/CD environment variables or a secrets manager such as Azure Key Vault or HashiCorp Vault. For more details, see how to implement authentication and authorization securely.


Tips and Good Practices

Of the book’s many lessons, these are the ones that make an immediate impact when applied day to day:

  • Boy scout rule: leave the code better than you found it. Small continuous improvements prevent degradation.
  • Invest in automation: Makefiles, pre-commit hooks, CI/CD — every minute invested saves hours in the future.
  • Document decisions, not the obvious: ADRs for architectural choices, README for project setup. Do not document what the code already says clearly.
  • Test as a defense: every test should protect against a real regression. Avoid tests that only test the framework.
  • Learn a new language every year: you do not need to master it — the goal is to expand the way you think.
  • Know your editor: shortcuts, snippets, extensions. Mastering your work tool is a productivity multiplier.
  • Prefer reversibility: feature toggles, blue-green deploys, automated rollback. Decisions that can be reverted quickly reduce the risk of changes.

Conclusion

The Pragmatic Programmer is not a book about technology — it is a book about mindset. The lessons on responsibility (own your code), automation (tools are your friends), communication (ADRs and documentation) and adaptability (knowledge portfolio) transcend any language or framework.

In this article, I explored the principles with the most impact on daily work: DRY to eliminate duplication, orthogonality for modular design, feature toggles for safe changes, intelligent tests with property-based testing and reproducible environments with Docker. Each of these concepts, when applied consistently, significantly raises code quality and delivery reliability.

Being pragmatic means being efficient without being stubborn. It is knowing when to follow patterns and when to break them. It is being aware that code exists to solve problems, not to inflate egos. If you want to start now: refactor something duplicated in your project, create a Makefile, write an ADR for your latest technical decision, or set up a container for your development environment.

Did you like this content? Leave a comment with the lesson from the book that most impacted your career, or share this article with someone on your team who has not read it yet.


Read Also


References