Short, Intuitive, and Descriptive (SID)

When we name our variables, functions, classes, or components, we should keep them short, intuitive, and descriptive. Short names are easy to type and remember. It should be intuitive and close to common speech so we can read it naturally. In the meantime, it should be descriptive enough to reflect what it does or possesses most efficiently.

Why SID Matters

Good variable names act as self-documentation, making code easier to understand and maintain. By following SID, we optimize for both developer efficiency and code readability.

Short

Short names are easy to type and remember. They reduce the cognitive load of reading and writing code. However, short names should not be cryptic or ambiguous. They should be concise but still convey the intended meaning.

• Keep names concise to reduce typing effort and cognitive load.
• Avoid unnecessary words or redundant information.
• Example: userCount instead of numberOfUsersInDatabase.

Intuitive

Intuitive names are close to common speech, making them easy to read and understand. They should be familiar to developers and reflect the natural language used in the problem domain.

• Use familiar terms that align with everyday language.
• Choose names that can be understood without deep context.
• Example: isActive instead of entityStateFlag.

Descriptive

Descriptive names convey the purpose or content of the variable, function, class, or component. They should provide enough information to understand the role or behavior of the entity without needing to inspect its implementation.

• Convey the variable's purpose or content clearly.
• Include essential qualifiers that distinguish similar variables.
• Example: pendingOrders instead of just items.

Finding the Right Balance

The key is striking a balance between these principles. A name that's too short might lack clarity, while an overly descriptive name can become unwieldy. Consider the context:

// Too short
const val = getUserData(); // What value?

// Too long
const allActiveUserAccountsInSystem = getUserData(); // Excessive

// Just right
const activeUsers = getUserData(); // Clear and concise

Practical Guidelines

1. Use domain terminology when it adds clarity.
2. Consider the scope—broader scope often requires more descriptive names.
3. Be consistent with naming patterns across our codebase.
4. Prioritize readability during code review and maintenance.

Remember: The best variable names make our code read like a well-written story, where each name contributes to the overall narrative of what our code does.