Code is read far more often than it’s written, yet most developers optimize for the few minutes spent writing it over the months it’ll spend being read, modified, and debugged by someone else — often a future version of themselves who’s forgotten the context entirely.
Naming: Say What, Not How
# Bad: what does this even do?
def calc(x, y, z):
return x * y * (1 - z)
# Good: the name IS the documentation
def calculate_discounted_total(price, quantity, discount_rate):
return price * quantity * (1 - discount_rate)
A good name eliminates the need for a comment explaining what a function does — it should be self-evident from the signature alone.
Functions Should Do One Thing
# Bad: validates, saves, AND sends an email — three responsibilities in one function
def process_signup(email, password):
if "@" not in email:
raise ValueError("Invalid email")
db.save_user(email, password)
send_welcome_email(email)
# Good: each function does exactly one thing, composed together
def validate_email(email):
if "@" not in email:
raise ValueError("Invalid email")
def process_signup(email, password):
validate_email(email)
db.save_user(email, password)
send_welcome_email(email)
Smaller, single-purpose functions are easier to test in isolation, easier to name accurately, and easier to reuse elsewhere without dragging in unrelated behavior.
Comments Should Explain Why, Not What
# Bad: restates what the code already clearly says # increment count by 1 count += 1 # Good: explains non-obvious reasoning the code alone can't convey # Retry once before failing — the upstream API occasionally # times out on cold start, per incident INC-4821 retry_count += 1
The Underlying Principle
Every one of these practices serves the same goal: minimizing the mental effort required for someone else (or future you) to understand what the code does and why. That’s the actual definition of “clean” — not a style preference, but a direct reduction in the cost of future changes.