Skip to main content

Naming Conventions

This guide establishes the naming standards used throughout the SureInk platform documentation and codebase.

Overview​

Consistent naming conventions ensure clarity and maintainability across documentation, code, and database schemas. The SureInk platform follows distinct conventions for business concepts versus technical implementations.

Business Entity Naming​

Convention: Plural Names​

When referring to business entities in documentation, use plural names to represent the collective concept or service.

Examples:

  • ✅ Customers entity
  • ✅ Subscriptions entity
  • ✅ Licenses entity
  • ✅ Orders entity
  • ✅ Products entity

Usage Contexts:

  • Documentation page titles
  • Business service descriptions
  • API endpoint paths (/api/customers, /api/subscriptions)
  • Service names in architecture diagrams
  • Navigation and sidebar labels

Rationale: Plural names emphasize that these are business services managing collections of resources, aligning with REST conventions and business domain language.

Technical Implementation Naming​

Convention: Singular Names​

When referring to actual code artifacts, database schemas, and Java classes, use singular names to represent individual instances.

Examples:

  • ✅ Customer (Java class)
  • ✅ CUSTOMER (database table)
  • ✅ Subscription (entity class)
  • ✅ LICENSE (database table)
  • ✅ Order (domain model)

Usage Contexts:

  • Java class names (Customer.java, Subscription.java)
  • Database table names in SQL and ERD diagrams
  • JPA entity annotations (@Entity, @Table)
  • Code comments and JavaDoc
  • Class diagrams and technical specifications

Rationale: Singular names represent individual objects/records, following Java naming conventions and database normalization principles.

Naming Matrix​

ContextFormatExampleNotes
Documentation SectionPlural"Customers"Page titles, headings
API EndpointsPlural/api/customersREST resource collections
Java ClassSingularCustomerEntity, DTO, Service classes
Database TableSingularCUSTOMERSchema definition
Package NameSingularcom.sureink.customerJava package structure
Service NameSingularCustomerServiceSpring service beans
RepositorySingularCustomerRepositoryData access layer
DTOSingularCustomerDtoData transfer objects

Specific Examples​

Documentation Header​

# Customers

The **Customers** entity is the "Source of Truth" for all customer-related data...

Entity Relationship Diagram​

Note: ERDs use singular CUSTOMER because they represent database schema.

Java Code​

@Entity
@Table(name = "customer", schema = "customer")
public class Customer {
    @Id
    private Long id;
    private String name;
    // ...
}

Documentation Reference​

The **Customers** entity (`Customer` Java class) stores profile information...

Note: Mix plural for business concept, singular in backticks for code reference.

Edge Cases and Exceptions​

1. Uncountable Nouns​

Some domain terms don't have clear plural forms:

  • "User Management" (not "Users Management")
  • "Usage Data" (not "Usages Data")

Rule: Use the natural English form. If the term is inherently collective, keep it singular.

2. Compound Names​

For multi-word entities:

  • Documentation: "Payment Quotes" (plural)
  • Java Class: PaymentQuote (singular)
  • Database: PAYMENT_QUOTE (singular)

3. Technical Terms​

Keep technical acronyms and terms as-is:

  • ✅ "API Gateway"
  • ✅ "JPA Repository"
  • ✅ "REST Controller"

File and Directory Naming​

Source Code​

sureink-customer/
  src/main/java/com/sureink/customer/
    model/
      Customer.java          # Singular
      CustomerAddress.java   # Singular
    repository/
      CustomerRepository.java  # Singular
    service/
      CustomerService.java     # Singular

Documentation​

docs/
  business-services/
    customers/               # Plural folder
      index.md              # "Customers" title
      customer-management.md # Descriptive filename

Rule: Documentation folders use plural, but filenames can be descriptive.

Common Mistakes to Avoid​

❌ Incorrect​

# Customer

The **Customer** entity manages individual customer records...

✅ Correct​

# Customers

The **Customers** entity manages individual customer records...

❌ Incorrect​

@Entity
public class Customers { // Wrong - Java classes are singular

✅ Correct​

@Entity
public class Customer { // Correct - singular for Java

❌ Incorrect​

✅ Correct​

Quick Reference Checklist​

When writing documentation or code, ask:

  1. Am I describing a business service/concept?

    • → Use plural ("Customers entity")

  2. Am I referring to a Java class or database table?

    • → Use singular (Customer, CUSTOMER)

  3. Am I writing an API path?

    • → Use plural (/api/customers)

  4. Am I naming a package or service bean?

    • → Use singular (com.sureink.customer, CustomerService)