Writing Python that runs is easy. Writing Python that someone else—or you six months from now—can read, change, and trust is another story. Almost none of this comes from language tricks; it comes from simple habits repeated with discipline.
Names That Say What They Do
A good name is the only documentation that never becomes outdated. d says nothing; overdue_days does. process() is vague; send_invoice() tells the story. When you need a comment just to explain what a variable contains, the name is usually the thing that is wrong.
Reserve short names for short scopes—the i in a three-line for loop is perfectly fine. Outside of that, favor clarity over saving keystrokes. No one has ever complained that a name was too readable.
Functions That Do One Thing
A function that validates the form, writes to the database, and sends the confirmation email is really three functions pretending to be one. The day you want to test only the validation, you will have to start the database and email server too. Separate them.
The practical test is the name: if you describe the function using an “and” (“validate and save and notify”), it probably does too much. Small, focused functions are easier to read, test, and reuse—and the calling code, which simply invokes them one after another, becomes almost a summary of what happens.
Don’t Abstract Too Early
There is an almost irresistible urge to see two similar pieces of code and immediately create a brilliant function that handles both. Resist it. Duplication is cheap and visible; the wrong abstraction is expensive and sticky. A function with seven parameters and three Boolean flags almost always came from an overly hasty generalization.
A practical rule is to wait until the pattern appears a third time before extracting it. By then, you have seen enough variation to know what is actually common. Abstract what has proved stable, not what you imagine might change someday.
Isolate the Environment and Pin Dependencies
“It works on my machine” is almost always a story about dependencies. A virtual environment per project (python -m venv .venv) prevents one project’s library from contaminating another and keeps your global Python installation clean.
More importantly, pin your versions. A requirements.txt file with fixed versions, or a tool that uses a lock file, ensures that whoever clones the repository tomorrow installs exactly what you tested today. An unpinned dependency is a silent update waiting to break the build at the worst possible moment.
Type Hints Where They Truly Help
Type hints do not make Python faster, but they make your editor and your colleagues much smarter. Add them where the benefit is greatest: at public boundaries—function signatures and return values. def calculate_total(items: list[Item]) -> Decimal: already says more than a paragraph of docstring.
Run a checker such as mypy in CI so these annotations are actually verified instead of becoming decoration. But do not go overboard by typing every obvious local variable—hints are a communication tool, not a tax. Where they do not clarify, they get in the way.
Explicit Errors and Testing as a Habit
An except Exception: pass is where bugs go to live for free. Catch the specific exception you know how to handle and let the rest bubble up—a loud error in the right place is infinitely better than a system that fails silently. Prefer failing early to masking the problem.
And tests are not a phase that comes after coding; they are part of writing code. You do not need to aim for 100% coverage on day one—start with edge cases and the paths that would hurt if they broke. A handful of good tests buys you something that no amount of manual care can provide: the confidence to refactor.
Clean code is not vanity or perfectionism. It is what lets you change quickly, without fear, when the requirements change—and they always do. Start with one habit, apply it in your next commit, and let the rest follow.