Why Naming Matters: Tips for Effective Naming Conventions

 In the world of IT, there’s a saying you often hear:

There are only two hard things in Computer Science: cache invalidation and naming things.
— Phil Karlton

While this may be a joke, it also holds a kernel of truth. Naming things in software design often sparks heated debates, and there’s a reason for that. Good naming conventions can significantly impact the readability, maintainability, and overall quality of the code.

Recently, I organized workshops to define our new platform API specification. Defining good names for the endpoints and parameters was a major part of these discussions. Establishing a few conventions and best practices upfront and referring back to them when in doubt helped remove subjectivity and emotion from the discussion, facilitating a more objective and productive dialogue.

So here are some typical best practices for naming variables, endpoints, parameters, classes, attributes, tables, etc.:

• Clear: A name should be self-explanatory and clearly describe its intent. If you need a comment to explain a name, the name is probably not clear enough. This means that clarity should be preferred over brevity and acronyms should be avoided as much as possible.

• Concise: A name should be concise, as long names are also hard to read. This means avoiding repetition and stating the obvious, but as mentioned above if choice needs to be made between brevity and clarity, choose for clarity.

• Pronounceable: A name should be easily pronounceable, as the reader with internally vocalize the name. A pronounceable name can therefore significantly improve code readability and maintainability.

• Professional: A name should be professional, as you never know who might read it in the future. This means avoiding inside jokes, offensive names, memes, temporary labels…​

• Consistent: Be as consistent as possible, i.e.
  

  • Use the same terminology everywhere and do not use synonyms (e.g. when using begin/end in one place, don’t use start/finish in another).

  • Ensure consistency in language, i.e. all names should be in the same language (preferably English), while also agreeing on US versus UK english (e.g. colour versus color).

  • If you use specific prefixes or suffixes for specific names, apply them always for the same types of names.

• Unique: Duplicate names should be avoided as much as possible. Ideally, each name should be sufficiently distinct from others to prevent confusion. Prefixes can help achieve this, and ideally, these prefixes can form a logical hierarchy, indicating relationships between different elements.

But defining just the name is not enough. Defining the style in which names are written is another area that can spark debates. Consistency in style is crucial, and once agreed upon, it should be adhered to rigorously.
Here are some common naming styles:

• Camel Case (camelCase): The first letter of the first word is lowercase, and the first letter of each subsequent concatenated word starts with an uppercase letter.
  Example: userProfile, calculateTotalAmount

• Pascal Case (PascalCase): Similar to camel case, but the first letter of the first word is also uppercase.
  Example: UserProfile, CalculateTotalAmount

• Snake Case (snake_case): Words are separated by underscores and all letters are lowercase.
  Example: user_profile, calculate_total_amount

• Kebab Case (kebab-case): Words are separated by hyphens.
  Example: user-profile, calculate-total-amount

• Space Case: Words are separated by spaces
  Example: User Profile, Calculate Total Amount

• Screaming Snake Case (SCREAMING_SNAKE_CASE): Like snake case, but all letters are uppercase.
  Example: USER_PROFILE, CALCULATE_TOTAL_AMOUNT

• Studly Caps: Alternating capitalization, usually starting with an uppercase letter. This isn’t standard and can vary.
  Example: UsErPrOfIlE, CaLcUlAtEtOtAlAmOuNt

• Train Case (Train-Case): Similar to Pascal Case, but words are separated by hyphens. It is like a combination of Pascal Case and Kebab Case.
  Example: User-Profile, Calculate-Total-Amount

• Start Case (Start Case): All words are capitalized and separated by spaces. Commonly used in titles or headers.
  Example: User Profile, Calculate Total Amount

• Lower case (lowercase): All characters are lowercase without any separation for multiple words.
  Example: userprofile, calculatetotalamount

• Upper case (UPPERCASE): All characters are uppercase without any separation for multiple words.
  Example: USERPROFILE, CALCULATETOTALAMOUNT

Naming is a crucial aspect of software design and development, and it’s often the source of strong opinions. By setting clear, consistent rules upfront, you can make the naming process more objective and reduce the potential for disagreement. Just as marketing departments have style guides, IT departments should have naming guides to ensure clarity and consistency across their deliverables. This will ultimately lead to more readable, maintainable, and professional software.