Clean Code

Clean Code: Naming Things Well

Phil Karlton's quip that naming things is one of the two hard problems in computer science is funny because it's true. Good names make code read like prose. Bad names force you to hold state in your head that the code should hold for you.

Published April 24, 2026

Names are the first thing a reader encounters when they open your code. A well-named variable, function, or class removes the need to explain what it does; a poorly named one requires comments that may or may not stay accurate over time. The goal is code that communicates intent directly.

Use names that reveal intent

A name should answer three questions: what it is, why it exists, and how it's used. If a name requires a comment to explain it, the name is not good enough yet.

# Bad: what is d? what does it represent?
d = 86400

# Better: the name tells you what it means
SECONDS_PER_DAY = 86400

# Bad: what does flag mean? active? deleted? premium?
if user.flag:
    send_email(user)

# Better: the condition reads like a sentence
if user.email_notifications_enabled:
    send_email(user)

Variables: nouns that describe what they hold

Variables hold values. Their names should be nouns or noun phrases that describe what the value represents, not how it's computed or what type it has.

# Bad: type-based names
int_count = 42
str_name = "Alice"
list_items = [1, 2, 3]

# Bad: single letters outside of conventional short loops
for i, x in enumerate(items):
    process(x)

# Better
for index, item in enumerate(items):
    process(item)

# Acceptable: very short loops where variable meaning is obvious from context
for i in range(10):
    ...

Boolean variables should read like a yes/no question: is_active, has_permissions, was_deleted, can_edit. Avoid negations in boolean names (is_not_disabled) because if not is_not_disabled is painful to read.

Functions: verbs that describe what they do

Functions perform actions. Their names should be verb phrases that describe the action, including what it returns or modifies.

# Bad: noun (sounds like a value, not an action)
def user_email(user):
    return user.email

# Better: verb phrase
def get_user_email(user):
    return user.email

# Bad: vague verb
def process_data(data):
    ...

# Better: specific verb
def normalize_phone_numbers(contacts):
    ...

Functions that return booleans should read like predicates: is_valid_email, has_exceeded_quota, can_publish. The test site checks naturally read as conditions: if is_valid_email(address):

Avoid noise words and encodings

Noise words add length without adding meaning. data, info, manager, handler, processor, helper — these are almost always avoidable. What data? What does the manager manage specifically?

# Noise words
class DataManager:
    def process_data_info(self, data_object):
        ...

# Specific
class InvoiceExporter:
    def export_to_pdf(self, invoice):
        ...

Hungarian notation (strName, intCount) was useful in weakly-typed languages from the 1980s. In modern statically typed or dynamically typed languages with good tooling, it adds noise without benefit.

Consistent vocabulary across the codebase

Pick one word per concept and use it everywhere. If you retrieve data from a database, choose get, fetch, or load and stick to it. Using all three interchangeably forces readers to wonder if there's a meaningful distinction.

Keep a short vocabulary list for your project: "we say create not make, remove not delete or destroy, fetch not get or load." This takes five minutes to establish and saves hours of confusion later.

Length vs. clarity

Names should be as long as they need to be and no longer. invoice_export_date is better than ied or d. It's also better than the_date_when_the_invoice_was_exported_to_the_client.

Scope is a useful guide to length: a variable that lives for two lines in a tight loop can be short. A field on a class that lives for the lifetime of an object should be descriptive enough to be understood out of context.

Rename freely and early

A bad name noticed early should be renamed immediately. Modern IDEs make project-wide renaming safe and instant. The cost of renaming is low; the cost of a misleading name compounding confusion across a growing codebase is high. Treat "I should rename this" as an immediate task, not a backlog item.

Good naming is the cheapest form of documentation because it lives in the code, can't get out of sync with the implementation, and costs nothing to read. It's worth the time it takes.