clean code

Clean code is code written to be read and changed by other people, favoring clear names, small focused functions, and straightforward control flow over cleverness or brevity. It’s a judgment about the state of a codebase rather than a process, and code that fails it accrues technical debt with every change.

Say a function has to work out whether a library loan came back late and by how many days. A dense version packs the rule into one line with names that give nothing away:

Python 
def calc(d1, d2, g=3):
    return max(0, (d2 - d1).days - g)

The clean version states the same rule in terms a reader already knows. The grace period and the floor at zero stop being puzzles to decode:

Python 
GRACE_PERIOD_DAYS = 3


def days_overdue(due_on, returned_on):
    late_days = (returned_on - due_on).days
    return max(0, late_days - GRACE_PERIOD_DAYS)

Both versions run the same arithmetic in the same time. The second one answers the question a reader actually arrives with.

How It Shows Up in Practice

Python has held this value since long before the phrase caught on. PEP 8 rests on the observation that “code is read much more often than it is written,” and PEP 20, the Zen of Python, puts it in two words: “Readability counts.”

The modern popularization comes from Robert C. Martin’s Clean Code (Prentice Hall, 2008), the source of the meaningful-names and small-functions advice teams still quote in review.

A developer meets the standard mostly in code review, where comments ask for a clearer name, a function split in two, or a comment deleted because the code now says it. Parts of it are automated. A linter such as Ruff or Pylint flags unused names and over-long functions, and a formatter such as Black settles layout so nobody relitigates it.

Teams that treat cleanliness as shippable work write it into their definition of done and file refactoring tickets when a code smell turns up, rather than waiting for a rewrite that never gets scheduled.

Common Pitfalls

The term has no objective test, which is where most of the friction comes from. One reviewer’s clean extraction is another’s maze of four-line helpers. Teams that argue about cleanliness in the abstract get further by agreeing on specifics instead: a naming convention, a function-length guideline, a formatter that ends the layout debate.

The other common failure is treating the standard as absolute. Polishing code nobody reads spends time that features or tests would repay better. The Zen of Python covers that case too with “practicality beats purity.” Clean code earns its keep where code changes often, and a file nobody touches rarely repays the polish.

How to Write Beautiful Python Code With PEP 8

Tutorial

How to Write Beautiful Python Code With PEP 8

Learn how to write readable, high-quality Python code by following the PEP 8 style guide and using linters and autoformatters to enforce it.

intermediate best-practices

For additional information on related topics, take a look at the following resources:

Have a question about this? Mentor AI can show you examples, compare related terms, and point you to tutorials.

  • Ask Mentor AI
  • Pick a question and Mentor AI takes it from here.
By Martin Breuss • Updated Oct. 18, 2026
Software Engineering Glossary Share Feedback