Why naming is the number one readability factor

Consider two versions of the same code. The logic is identical, only the names differ.

// Version A: AI default names
async function getData(id) {
  const result = await fetch(`/api/items/${id}`);
  const data = await result.json();
  const filtered = data.filter(item => item.status === 'active');
  const mapped = filtered.map(item => ({
    ...item,
    label: `${item.first} ${item.last}`
  }));
  return mapped;
}

// Version B: domain-specific names
async function getActiveTeamMembers(teamId) {
  const response = await fetch(`/api/teams/${teamId}/members`);
  const members = await response.json();
  const activeMembers = members.filter(member => member.status === 'active');
  const membersWithDisplayName = activeMembers.map(member => ({
    ...member,
    displayName: `${member.firstName} ${member.lastName}`
  }));
  return membersWithDisplayName;
}

Version B takes zero extra time to write (AI will generate it if you prompt well), but it is dramatically easier to understand. You can read getActiveTeamMembers(teamId) and know what it does without reading the body. You can see activeMembers.filter(...) and know exactly what is being filtered. Every name tells you what the data actually is.

AI naming patterns and how to fix them

AI falls into predictable naming traps. Once you know the patterns, you can spot and fix them quickly.

The generic name problem

AI defaults to generic names because it optimizes for being "correct" across all possible contexts rather than specific to yours.

The fix is always the same: replace the generic word with a domain-specific one. Ask yourself "what does this variable actually contain?" and use that as the name.

The over-verbose problem

The opposite extreme is AI generating names so long they hurt readability.

// AI-generated verbose names
const getAllUserDataFromDatabaseByUserId = async (userId) => { ... };
const isCurrentUserAuthenticatedAndHasAdminPermissions = () => { ... };
const filteredAndSortedProductListWithDiscountsApplied = products.filter(...);

These names try to describe the entire implementation in the variable name. The result is code that wraps across your screen and is painful to use at call sites.

// Better: concise but descriptive
const getUser = async (userId) => { ... };
const isAdmin = () => { ... };
const discountedProducts = products.filter(...);

The rule of thumb: a name should describe what the thing is or does, not how it works. getUser tells you the purpose. getAllUserDataFromDatabaseByUserId tells you the implementation (and will become a lie when you add caching).

The inconsistent naming problem

Across multiple AI prompts, you end up with inconsistent naming for the same concepts.

// Three different conventions for the same concept in one project
const user_name = 'Alice';       // snake_case (AI prompt 1)
const userEmail = 'a@test.com';  // camelCase (AI prompt 2)
const UserAge = 25;              // PascalCase (AI prompt 3)

// Three different verbs for the same operation
function fetchUsers() { ... }    // fetch
function getOrders() { ... }     // get
function retrieveProducts() { .. } // retrieve

Naming conventions by category

Consistency matters more than any specific convention. Pick one style and stick with it across your entire project.

Variables and functions

Use camelCase in JavaScript and TypeScript. Name variables as nouns (what they contain) and functions as verbs (what they do).

// Variables: nouns describing the data
const activeUsers = [];
const maxRetryCount = 3;
const isAuthenticated = true;

// Functions: verbs describing the action
function calculateTotal(items) { ... }
function validateEmail(input) { ... }
function formatCurrency(amount) { ... }

Boolean variables should read as yes/no questions: isLoading, hasPermission, canEdit, shouldRefresh. Avoid negated booleans like isNotReady, use isReady and negate at the call site.

Components

React components use PascalCase and should describe what they render, not what they do internally.

// Good: describes what it renders
function UserProfileCard({ user }) { ... }
function OrderSummary({ order }) { ... }
function PaymentMethodSelector({ methods, onSelect }) { ... }

// Bad: describes implementation or is too vague
function DataDisplayComponent({ data }) { ... }
function ContainerWrapper({ children }) { ... }
function HelperComponent({ config }) { ... }

Event handlers

Prefix with handle in the component that defines them and on in the propsWhat is props?Data passed from a parent component to a child component, used to configure what the child displays or does. Ask AI for more that receive them.

// Parent component defines handlers
function CheckoutPage() {
  const handlePaymentSubmit = (paymentData) => { ... };
  const handleCouponApply = (code) => { ... };

  return (
    <PaymentForm
      onSubmit={handlePaymentSubmit}
      onCouponApply={handleCouponApply}
    />
  );
}

File and folder naming

File names are the first thing you see when navigating a project. They should tell you what is inside without opening the file.

# Bad: generic or unclear
src/
  utils.js         # utils for what?
  helpers.js        # same question
  data.js           # data from where?
  types.js          # for the whole app?
  index.js          # one of twelve index.js files

# Better: specific and scannable
src/
  pricing-utils.js
  date-formatting.js
  cart-calculations.js
  user-types.ts
  order-types.ts

Pick either kebab-case or PascalCase for component files, both are common, and use it everywhere.

The "read it out loud" test

This is the simplest and most effective naming test. Read the code out loud as if you were explaining it to someone. If it sounds awkward, the name is wrong.

// Read out loud: "get data from thing by value"
const result = getData(thing, value);
// Verdict: meaningless. What data? What thing? What value?

// Read out loud: "get active subscriptions for user ID"
const activeSubscriptions = getActiveSubscriptions(userId);
// Verdict: perfectly clear. You know exactly what this does.

Try it with function definitions too:

// "process items" - process them how? into what?
function processItems(items) { ... }

// "apply bulk discount to order items" - clear and specific
function applyBulkDiscount(orderItems) { ... }

When the read-aloud test produces a clear sentence, your names are good. When it produces vague mush, rename until it reads like a sentence a teammate would understand.

Renaming in practice

When you refactor names in an existing codebase, use your editor's rename functionality (F2 in VS Code) rather than find-and-replace. Rename is scopeWhat is scope?The area of your code where a variable is accessible; variables declared inside a function or block are invisible outside it. Ask AI for more-aware, it changes the variable everywhere it is used without accidentally replacing unrelated text that happens to contain the same letters.

For larger renames (changing a concept name across many files), do it in a separate commitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. Ask AI for more with no logic changes. This makes the rename easy to review and easy to revert if something breaks. Mixing logic changes with renames in the same commit is a recipe for missed bugs.