Software Development Best Practices

Contents

TL;DR

  • A one-page map of the practices behind maintainable software: how teams plan (Agile), ship (DevOps, CI/CD), test (TDD, BDD), model the problem (DDD), and write and review code (clean code, SOLID, design patterns, refactoring, code review, pairing).
  • Each section explains the idea and why it helps, plus when it doesn’t fit. These are tools, not rules; knowing when not to use one is part of the skill.
  • If you only adopt one practice, make it CI/CD: a pipeline that runs the linter and tests on every push catches many problems before a human reviewer ever sees them.
  • You don’t need all of it on day one: start with CI, small reviewed pull requests, and refactoring as you go. These practices matter more, not less, when AI agents write most of the code.

Introduction

It’s aimed at developers early in their career who keep hearing these acronyms, and at anyone who wants a one-page refresher. Each section also says when the practice doesn’t fit.

Agile methodology

Agile means building software in small increments and changing course based on what you learn. In practice that looks like this:

  • Work is split into short iterations called sprints, usually one to four weeks long (two is the most common). Each sprint ends with an increment you could ship.
  • Customers see the work often, and their feedback decides what comes next.
  • One team holds all the skills needed to ship: developers, testers, designers and a product owner.
  • When requirements or priorities change, the plan changes with them. Nobody defends a six-month-old spec.
  • The team regularly looks back at how it works and adjusts. In Scrum this is the retrospective at the end of each sprint.

Scrum, Kanban and Extreme Programming (XP) are the best-known frameworks. Each turns these ideas into concrete meetings, roles and limits.

Agile Methodology

DevOps principles

DevOps (Development and Operations) removes the wall between the people who write the software and the people who run it. The same team builds, ships and operates the service. The main habits:

  • Developers and operations share goals and talk early, instead of meeting for the first time during an outage.
  • Repetitive work (deployments, tests, provisioning servers) is automated, because scripts don’t forget a step at 3 a.m.
  • Continuous Integration (CI). Developers merge their code into a shared repository often, and automated tests run on every merge, so integration problems show up early.
  • Continuous Deployment (CD). Changes that pass the automated tests go to production without a manual step, so releases get smaller and more frequent.
  • The team monitors the application and infrastructure in production and feeds what it sees back into the work.
  • Infrastructure as Code (IaC). Servers, networks and configuration are defined in code, so every environment is built the same way and can be rebuilt.
  • Security checks run throughout the pipeline instead of as a gate at the end.
  • Systems are designed to fail and recover without a long outage.
  • Code and infrastructure configuration both live in version control (usually Git), so every change has an author and can be reverted.
DevOps

Continuous integration and continuous deployment (CI/CD)

CI and CD are the two DevOps practices you’ll touch every day, so they get their own section.

Continuous integration (CI)

With CI, every developer merges small changes into the shared repository often, at least daily. Each merge triggers an automated build and test run. What you get:

  • The build and tests run without anyone remembering to run them.
  • Changes stay small, because they’re merged often.
  • Bugs and merge conflicts surface hours after they’re written, not weeks.
  • Everyone works on top of the same, current code.

Continuous deployment (CD)

CD takes CI one step further: once a change passes every test, it goes to production automatically. It needs CI underneath it, because the tests are the only thing standing between a commit and your users. What you get:

  • No manual deployment steps to get wrong.
  • Many small releases instead of a few big, scary ones.
  • A fix for customer feedback can be live the same day.

A CI/CD pipeline runs every change through the same stages: commit, build, automated tests and, if everything passes, deployment. Because the steps never change, there’s no release-day checklist for a person to skip.

If you only adopt one practice from this post, make it this one: a pipeline that runs the linter and the tests on every push catches many problems before a human reviewer ever sees them.

CI/CD

Test-Driven Development (TDD)

In Test-Driven Development (TDD) you write the test before the code it tests.

Flow of TDD

The cycle is short and you repeat it constantly:

  1. Write a test that describes the behavior you want.
  2. Run it and watch it fail. The code doesn’t exist yet, so it should.
  3. Write the smallest amount of code that makes the test pass.
  4. Run the test suite again. Everything should pass now.
  5. Refactor the code to make it cleaner, with the tests still passing.
  6. Repeat for the next behavior.

Benefits of TDD

  • Every behavior starts with a test, so less code ships untested. The research on whether that means fewer bugs is mixed: a 2013 meta-analysis found a small quality gain over waterfall-style testing, and no gain in the academic studies that compared TDD with writing tests right after the code. The clearer wins are the next three points.
  • The tests are a specification: they say exactly what the code is supposed to do.
  • When something breaks, the failing test points at the behavior that broke.
  • The suite catches regressions when later changes break old behavior.

TDD also tends to push you toward smaller, more modular code, because code that’s hard to test is usually code that does too much. It feels slow at first and gets faster with practice.

When it fits less well: exploratory spikes and prototypes you’ll throw away, and UI layout work, where the right answer is found by looking at it. Write the test once you know what the code should do.

Test-Driven Development

Behavior-Driven Development (BDD)

Behavior-Driven Development (BDD) describes what the software should do from the user’s point of view, in sentences that developers, testers and domain experts can all read. Cucumber, SpecFlow and Behave are the common tools: they turn those sentences into tests.

Main aspects of BDD

  • Given-When-Then scenarios. Each scenario states the starting context (Given), the action (When) and the expected outcome (Then). Writing them together forces the team to agree on how the system should behave.
  • Developers, testers and domain experts write and review the scenarios together, so misunderstandings come out before the code is written.
  • The scenarios run as automated tests, so they’re documentation that fails when it goes out of date.

In Python, pytest-bdd and behave run Given-When-Then scenarios as tests.

When it fits less well: if no business stakeholder ever reads the scenarios, the Gherkin layer is just a slower way to write tests. Plain pytest tests with descriptive names give you most of the benefit.

Domain Driven Design (DDD)

Domain Driven Design models the software on the business it serves: the code uses the business’s concepts and words, so the people who know the business can follow what it does.

Core concepts

  • Domain. The problem space: the area or industry the software is built for. DDD starts by understanding it well.
  • Ubiquitous language. Domain experts and developers use the same terms, and those terms appear in the code as class and function names.
  • Bounded contexts. In a large application, different parts of the domain get their own separate models, each with its own rules and terms. “Customer” can mean something different in billing than in support, and that’s fine.
  • Aggregates. Clusters of related entities and value objects inside a bounded context that change together and keep their own rules consistent.
  • Entities and value objects. An entity has an identity that lasts (a customer with an ID); a value object is defined only by its values and doesn’t change (an amount of money).

Benefits

The domain logic is explicit, so developers and domain experts can talk about the same code. The structure follows the business, so a new requirement usually lands in an obvious place. And when the code uses the same words as the business, a misunderstanding shows up in a conversation instead of in production.

When it fits less well: CRUD apps and thin services with little business logic. The ubiquitous language is worth having everywhere; aggregates and the rest of the tactical patterns are only worth it where the domain is genuinely complex.

Bounded contexts are also the natural seams if you ever split a system into services. If you’re weighing that move, I compare both sides in Microservices vs. Monolithic.

Clean code principles

Clean code is code another developer can read, understand and change without asking you. It decides whether a project is still changeable in a year, and the organization of the code matters more than how it looks.

Main principles of clean code

  • Meaningful names. A name should say what a variable holds or what a function does.
  • Small functions. Each function does one thing.
  • Single Responsibility Principle (SRP). Each class or module has one job. Watch out for “god” objects that do everything.
  • Don’t Repeat Yourself (DRY). Move duplicated logic into one function or class.
  • Few comments. Write code that explains itself, and keep comments for the why the code can’t say.
  • Consistent formatting. One style across the project, ideally enforced by a formatter.
  • Unit tests. Tests prove the code works and let you change it safely. Writing them before the code is Test-Driven Development (TDD), covered above.
  • Refactoring. Clean code stays clean only if you keep improving it.

Benefits of clean code

Other developers can read it without a walkthrough, changes cost less, and simple code is easier to test, so errors surface earlier.

SOLID principles

SOLID is an acronym for five design principles for object-oriented code:

  • Single Responsibility Principle (SRP). A class should have only one reason to change.
  • Open/Closed Principle (OCP). Classes, modules and functions should be open for extension but closed for modification. In practice: add new functionality through inheritance or interfaces, and leave existing code alone.
  • Liskov Substitution Principle (LSP). A subclass must work anywhere its base class works, without breaking the program.
  • Interface Segregation Principle (ISP). Clients shouldn’t depend on methods they don’t use. Several small, specific interfaces beat one large one.
  • Dependency Inversion Principle (DIP). High-level modules shouldn’t depend on low-level modules; both should depend on abstractions.

They overlap with the clean code principles above; SRP appears in both lists.

Design patterns

Design patterns are named, reusable solutions to problems that keep coming up in software design. The names are as useful as the solutions: “use a strategy here” says a lot in three words. These are the classic ones:

Creational patterns

  • Singleton. Ensures a class has only one instance and provides a global point of access to it. Use it sparingly: a singleton is global state, and it makes testing harder. In Python, a module-level constant or one instance passed in through the constructor (dependency injection) usually does the job better.
  • Factory Method. Defines an interface for creating an object but lets subclasses decide which class to create.
  • Abstract Factory. Creates families of related objects without naming their concrete classes.
  • Builder. Separates building a complex object from its representation, so the same steps can produce different results.
  • Prototype. Creates new objects by copying an existing one, the prototype.

Structural patterns

  • Adapter. Lets an existing class be used through a different interface.
  • Decorator. Adds responsibilities to an object at runtime.
  • Composite. Builds objects into trees to represent part-whole hierarchies.
  • Proxy. Stands in for another object to control access to it.
  • Bridge. Separates an object’s abstraction from its implementation.

Behavioral patterns

  • Observer. When one object changes state, all its dependents are notified and updated automatically.
  • Strategy. A family of interchangeable algorithms, each in its own object.
  • Command. A request wrapped in an object, so you can queue, log or undo it.
  • Chain of Responsibility. Passes a request along a chain of handlers until one deals with it.
  • State. An object changes its behavior when its internal state changes.
  • Memento. Saves an object’s internal state so it can be restored later.
  • Interpreter. Evaluates sentences in a small language or grammar.
  • Visitor. An operation on the elements of an object structure, defined outside those elements’ classes.
  • Mediator. One object handles the communication between others, so they don’t depend on each other directly.
  • Template Method. The superclass defines the steps of an algorithm and subclasses override some of them.

When they fit less well: most of these patterns come from Java and C++. In Python, first-class functions, modules and duck typing make several of them a few lines of plain code (a Strategy is often just a function you pass in). Reach for a pattern when the problem shows up, not to have used one.

Code refactoring

Refactoring changes the structure of existing code without changing what it does. You do it in small, incremental steps: rename, extract, move, simplify, and run the tests after each one.

Why refactor?

Code that’s easier to read leads to fewer mistakes. Paying down technical debt as you go keeps the next change cheap. And untangling complex code often turns up bugs that were hiding in it.

When to refactor

Refactor all the time, in small amounts, and especially in these situations:

  • When you spot a code smell (long methods, duplicated code, complex conditionals; see the next section).
  • Before adding a feature, so the existing code has room for it.
  • While debugging, to isolate the problem in a piece of code small enough to reason about.

Common refactoring techniques

  • Extract Method. Split a long method into smaller ones with descriptive names.
  • Rename. Give variables and functions names that say what they’re for.
  • Remove Duplication. Merge repeated code so a fix only has to happen once.
  • Simplify Conditionals. Flatten nested if-else blocks into something you can read top to bottom.
  • Simplify Loops. Replace index juggling with a comprehension or a built-in (sum, any, zip) where it reads better. That’s a readability change; a speed claim needs a measurement.
  • Extract Class. Split a large class into smaller ones, each with a single responsibility.
  • Move Code. Put code where it belongs, next to the data it works on.

How to refactor safely

Commit before you start, so you can always go back. Make sure tests cover the code first; if they don’t, write them before touching anything. Then change one small thing at a time and run the tests after each step.

Identifying code smells

A code smell is a pattern in the code that hints at a deeper problem. It isn’t a bug, but it often leads to one. These are the ones you’ll meet most often:

Duplicate code (DRY violation)

  • The same code repeated in several places.
  • Solution. Extract it into a function or class.

Long methods

  • Methods or functions that go on for screens.
  • Solution. Break them into smaller, focused ones.

Large classes

  • Classes with too many responsibilities and methods.
  • Solution. Apply the Single Responsibility Principle (SRP) and split them.

Complex conditionals

  • Deeply nested if-else statements.
  • Solution. Use guard clauses and early returns, replace long if/elif chains with a lookup table or a match statement, or move type-based branching into polymorphism.

Inconsistent naming

  • The same concept named differently across variables, functions or classes.
  • Solution. Agree on a naming convention and apply it everywhere.

Excessive comments

  • Code that only makes sense with the comments next to it.
  • Solution. Simplify the code and let good names do the explaining.

Feature envy

  • A method that uses another class’s data more than its own.
  • Solution. Move the method to the class whose data it uses.

Data clumps

  • The same group of variables passed around together again and again.
  • Solution. Put them in their own class or structure.

Inappropriate intimacy

  • Classes that are too tightly coupled and violate the Law of Demeter.
  • Solution. Refactor to reduce dependencies and keep coupling loose.

The Law of Demeter (LoD) says an object should know as little as possible about the internals of other objects. An object talks only to its immediate neighbors, not to objects further away in the system. That keeps coupling low and the system easier to change.

Code review best practices

Code review keeps quality up, keeps style consistent and catches problems before they merge. These habits make reviews worth the time (for the concrete, rule-by-rule checklist I use on Python code, see An Opinionated Python Code Review Guide):

  • Know what you’re reviewing for. Bugs, style or architecture? Saying so up front helps reviewers focus.
  • Pick the right reviewers. Include whoever knows the area: another developer, an architect or a domain expert.
  • Keep changes small. Large changes hide mistakes, and nobody gives useful feedback on a 2,000-line diff.
  • Use the tooling. GitHub, GitLab and Bitbucket all track comments and changes for you.
  • Agree on coding standards. Write them down and review against them, not against personal taste.
  • Be specific. Instead of “This is bad”, write “Consider a more descriptive variable name”.
  • Fix what matters first. Critical problems before nitpicks.
  • Suggest, don’t just reject. If you point out a problem, offer an alternative and talk it through.
  • Automate the boring part. Linters and formatters catch style issues before a person has to.
  • Review promptly. A pull request that waits for days drifts from main and slows everyone down.
  • Follow up. Check that the feedback was addressed before approving.
  • Document the change. A clear commit message and the right comments help the next reader.
  • Learn from it. Reviews are one of the best ways to share knowledge across a team.

Pair programming

In pair programming, two developers work on the same code at the same computer. The “driver” writes the code; the “navigator” (or “observer”) reviews it as it’s written, suggests improvements and thinks ahead. They swap roles often.

Benefits of pair programming

  • Two people looking at the code catch more mistakes as they happen, including code smells.
  • Developers pick up each other’s skills and techniques.
  • On hard problems, two people get unstuck sooner. On routine tasks, pairing usually costs more person-hours than it saves.
  • Knowledge spreads across the team instead of staying with one person.
  • Developers tend to trust code they’ve built and checked together.

Best practices for pair programming

  • Rotate pairs regularly so knowledge spreads and nobody burns out.
  • Talk constantly: the navigator says what they’re thinking, and the driver says what they’re doing.
  • Agree on a goal for each session.
  • Pair people with different skills and experience.
  • Use an editor or IDE that supports remote pairing if you’re not in the same room.
  • Close chat and email while pairing.

When to use pair programming

Pairing pays off most on complex problems where two heads really are better than one, when onboarding someone new to the codebase, and as a real-time code review on risky changes.

When it fits less well: routine, well-understood tasks, and anything that needs quiet reading or research first. Pairing all day is also tiring; most teams pair for a part of the day, not all of it.

Mob programming

Mob programming takes pairing further: the whole team, usually three or more people, works on the same code at the same time.

Main aspects of mob programming

  • Driver and navigators. One person types (the driver) while the others guide, suggest ideas and review in real time (the navigators). The driver role rotates.
  • Collective ownership. The whole mob is responsible for the code, so everyone understands it.
  • Continuous collaboration. Problem solving and knowledge sharing happen all the time, not in scheduled meetings.

Benefits of mob programming

With several people watching, design decisions get challenged early and fewer bugs slip through. Knowledge silos disappear, so the team copes better when someone is away. Juniors learn fast by watching seniors work. And because the whole team is in one place on one problem, there are fewer interruptions and less context switching.

When to use mob programming

Mob programming works best for complex problems and gnarly bugs. Some tasks still go better solo.

Conclusion

That’s the map: Agile and DevOps for how the team works, CI/CD to ship safely and often, TDD and BDD to prove the code does what it should, DDD to model the problem, and clean code, SOLID, design patterns, refactoring and code review to keep the codebase something people can still change next year. Pair and mob programming spread that knowledge across the team.

You don’t need all of it on day one. Start with CI running your tests, small reviewed pull requests, and refactoring as you go, then add the rest as the pain points show up.

The biggest shift right now is AI-generated code: these practices matter more, not less, when agents write most of it. I cover that in From Programmers to Orchestrators and show my day-to-day setup in How I Work with AI Agents.

Back to all Posts