First Principles: Naming Is Design, Not Decoration

I've reviewed thousands of lines of AI-generated code this year. The single strongest predictor of whether the code was correct wasn't test coverage or type hints. It was whether the names made sense. When the agent picked bad names, the logic was almost always also wrong. The names were the canary.

Names Are the Spec

A function name is a contract. send_email promises to send an email. maybe_send_email_if_user_wants promises something muddier and harder to test. The mud in the name is mud in the thinking.

This is true for humans writing code. It's triply true when an AI agent is writing. The agent infers what a function should do partly from its name. A bad name produces bad code. A good name produces code that matches your intent.

The Naming Test

Before I let the agent implement a function, I check whether the name passes three questions:

• Could a stranger guess the return type?
• Could a stranger guess the side effects?
• Does the name hide any conditionals?

If any answer is no, I rename before generating. A minute on names saves an hour of debugging.

# Hidden conditional in the name
def send_email_if_verified(user): ...
 
# Conditional exposed, function name simpler
def send_verification_email(user): ...
def is_verified(user): ...
if is_verified(user):
    send_verification_email(user)

Why This Matters More With Agents

When a human reads a function name, they sometimes notice the name is off and think about it. Agents don't stop to think. They generate. Good names in, good code out. The bar for names went up, not down, in the AI era.