How to Create Consistent and Clear Naming Conventions in Coding?

Apr 28

Effective naming conventions are essential for writing code that is readable, maintainable, and scalable. In this article, we’ll explore a practical guide on establishing clear naming conventions for your coding projects.

1. Overriding Principles: Prioritize Clarity and Readability

A good name tells a story at a glance.

Think about the reader: Names should make it obvious what something represents, not how it is implemented internally.

Public-facing names (APIs, public methods) should describe what they do, so that developers can use them without needing to read the source code.

Avoid clever or ambiguous names that make code harder to understand.

2. Descriptive Naming: The Power of Consistency

Consistency makes your codebase predictable and easier to onboard new developers.

Common Naming Styles:

  
      Style
      Example
      Usage Example
    
      camelCase
      myVariableName
      JavaScript variables, some APIs
    
      snake_case
      my_variable_name
      Python functions, variables
    
      PascalCase
      MyClassName
      Class names, Typescript types
    
      kebab-case
      my-variable-name
      URLs, file names
    
      ALL_CAPS_WITH_UNDERSCORES
      MAX_SIZE_LIMIT
      Constants

camelCase: Capitalize each word except the first.
snake_case: Lowercase words separated by underscores (recommended for Python).
ALL_CAPS: All uppercase letters with underscores (commonly used for constants).
kebab-case: Lowercase words separated by hyphens (often used in URLs or file names).
PascalCase: Capitalize the first letter of every word (recommended for class names).

Python-specific conventions:

_single_leading_underscore: Indicates “internal use”.
__double_leading_underscore: Triggers Python’s name mangling for private attributes.
single_trailing_underscore_: Used to avoid conflicts with Python keywords.
__double_leading_and_trailing_underscore__: Reserved for Python’s special methods (“magic methods”).

Recommended Usage:

Variables and functions ➔ snake_case
Classes ➔ PascalCase
Global constants ➔ ALL_CAPS

3. Prescriptive Naming Conventions: Avoiding Common Pitfalls

Avoid unnecessary abbreviations — “shortcuts” make code shorter but harder to understand.

General Good Practices:

Avoid confusing characters: Never name variables just “l”, “I”, or “O”. They’re too easy to mix up with “1” and “0”.
ASCII-only identifiers: Stick to ASCII to avoid cross-platform encoding problems.

Specific Cases:

  
      Item
      Naming Rule
    
      Packages
      Short, lowercase, no underscores
    
      Modules
      snake_case allowed for readability
    
      Functions
      Prefer snake_case
    
      Global Variables
      ALL_CAPS recommended
    
      Local Variables
      Follow function naming convention (snake_case)
    
      Classes
      PascalCase — clear, descriptive names
    
      Exception Classes
      End with "Error" in PascalCase (e.g., LoginError)
    
      Constants
      ALL_CAPS with underscores

4. API Endpoint Naming: RESTful and Intuitive

Your API should be intuitive enough that users can guess the endpoints.

REST API Naming Principles:

Resource-oriented, not action-oriented.
Nouns, not verbs.
Use kebab-case for paths (/user-profiles).
Use plurals for collections: /users, /products.

  
      HTTP Method
      Endpoint
      Purpose
    
      GET
      /users
      Fetch list of users
    
      GET
      /users/{id}
      Fetch a single user by ID
    
      POST
      /users
      Create a new user
    
      PUT
      /users/{id}
      Update a user
    
      DELETE
      /users/{id}
      Delete a user

5. Field Naming Consistency Across Backend and Frontend

Consistency across systems = less confusion, fewer bugs, faster development.

Field Naming Rules:

All lowercase
Use underscores to separate words
Avoid redundant prefixes (e.g., user_user_id ➔ user_id)
Align names exactly across SQL, backend models, API responses, and frontend states.

  
      Category
      Field Example
      Notes
    
      ID Fields
      user_id, order_id
      Always suffix with _id for clarity
    
      Timestamps
      created_at, updated_at
      Use _at suffix for datetime fields
    
      Boolean Flags
      is_active, has_paid, can_edit
      Prefix with is_, has_, or can_
    
      Names
      full_name, display_name
      Use clear and descriptive names
    
      Foreign Keys
      user_id, farm_id
      Reference the related table name + _id

Field names must remain consistent across every layer:

Database schema
Backend code (ORMs, API serialization)
Frontend code (JSON parsing, state management)

SIMPLE RULE: snake_case everywhere, even in JSON APIs.

6. Conclusion

Establishing consistent and clear naming conventions is not just about aesthetics. It’s about building software that is:

More understandable for new developers
Easier to maintain over time
More scalable for future features

Whether you’re working on backend APIs, frontend apps, databases — good naming conventions make everything better.

Phú Đoàn Vĩnh