Naming Conventions

This document defines the naming conventions used throughout the ReX project, ensuring consistency in code, documentation, and APIs.

General Principles

1. Consistency: Naming should be consistent across related elements
2. Clarity: Names should clearly indicate purpose and behavior
3. Explicitness: Prefer explicit, descriptive names over short, ambiguous names
4. Context-Awareness: Names should reflect their operational context

File Naming Conventions

TypeScript/JavaScript Files

• Implementation Files: Use kebab-case.ts for implementation files

  • Example: content-store.ts, filesystem-adapter.ts

• Type Definition Files: Use kebab-case.types.ts for standalone type files

  • Example: content.types.ts, adapter.types.ts

• Test Files: Use kebab-case.test.ts for test files

  • Example: content-store.test.ts, filesystem-adapter.test.ts

Documentation Files

• Markdown Files: Use kebab-case.md for documentation files

  • Example: content-model.md, layer-boundaries.md

• Architecture Decision Records: Use ADR-NNN-Title-With-Hyphens.md for ADRs

  • Example: ADR-007-Compositional-Content-Architecture.md

Code Naming Conventions

Interfaces and Types

• Interfaces: Use PascalCase without I prefix for interfaces

  • Example: ContentStore, ContentAdapter, ContentMetadata

• Type Aliases: Use PascalCase for type aliases

  • Example: ContentType, AdapterOptions, StorageOptions

• Generic Type Parameters: Use PascalCase single letters or descriptive names

  • Example: T for general types, TData for data types, TMetadata for metadata types

Options Interfaces

• Options Interfaces: Use {EntityName}Options pattern for all options interfaces

  • Example: ContentReadOptions (not just ReadOptions)
  • Example: LoggingMiddlewareOptions (not just LoggingOptions)
  • Example: FileSystemAdapterOptions (specific adapter options)

• Options Naming Patterns:

  • Operation options: Content{OperationName}Options (e.g., ContentReadOptions, ContentWriteOptions)
  • Middleware options: {MiddlewareName}MiddlewareOptions (e.g., LoggingMiddlewareOptions, CachingMiddlewareOptions)
  • Adapter options: {AdapterName}AdapterOptions (e.g., FileSystemAdapterOptions, HttpAdapterOptions)
  • Factory options: {EntityName}FactoryOptions (e.g., ContentStoreFactoryOptions)

Functions and Methods

• Factory Functions: Use create prefix for factory functions

  • Example: createContentStore, createFileSystemAdapter

• Higher-Order Functions: Use with prefix for higher-order functions (that enhance another function)

  • Example: withValidation, withCaching, withLogging

• Event Handlers/Callbacks: Use handle or on prefix for event handlers

  • Example: handleChange, onContentUpdate

• Asynchronous Functions: No special prefix, but always return Promises

  • Example: read, write, delete (not readAsync, etc.)

• Boolean Functions/Properties: Use is, has, can, or should prefix for boolean functions/properties

  • Example: isModified, hasChanges, canWrite, shouldRevalidate

Variables and Constants

• Constants: Use UPPER_SNAKE_CASE for truly constant values

  • Example: DEFAULT_TIMEOUT, MAX_RETRY_COUNT

• Configuration Objects: Use camelCase for configuration objects

  • Example: storeConfig, adapterOptions

• Regular Variables: Use camelCase for regular variables

  • Example: contentStore, fileAdapter, metadataValue

CSS Classes and IDs

• CSS Classes: Use kebab-case for CSS classes

  • Example: content-container, editor-panel

• CSS Variables: Use kebab-case with double hyphens for variable namespace

  • Example: --primary-color, --font-size-base

URI/Path Conventions

• Content URIs: Use kebab-case for path segments

  • Example: content/blog-posts/my-first-post

• API Endpoints: Use kebab-case for API endpoints

  • Example: /api/content-store/items

Event Naming Conventions

• Event Types: Use past tense to indicate something that happened

  • Example: created, updated, deleted, moved

• Event Handlers: Use on prefix followed by the event name in present tense

  • Example: onChange, onUpdate, onDelete

Common Domain-Specific Terms

To maintain consistency across all documentation and code, the following terms should be used consistently:

• Content: The fundamental unit of data in the system (not “document”, “resource”, etc.)
• URI: The identifier for content (not “path”, “id”, etc.)
• Metadata: Structured data about content (not “meta”, “attributes”, etc.)
• Adapter: Storage implementation abstraction (not “provider”, “connector”, etc.)
• Middleware: Function that enhances operations (not “interceptor”, “handler”, etc.)
• Store: High-level content operations API (not “repository”, “service”, etc.)

Special Considerations

React Components

• Component Files: Use PascalCase for component files

  • Example: ContentDisplay.tsx, ContentEditor.tsx

• Component Names: Use PascalCase for component names

  • Example: ContentDisplay, ContentEditor

• Hook Files: Use camelCase with use prefix for hook files

  • Example: useContent.ts, useContentStore.ts

• Hook Names: Use camelCase with use prefix for hook names

  • Example: useContent, useContentStore

Versioning-Related Names

• Temporal Field Names: Use consistent timestamp field names
  • createdAt: When the entity was created
  • updatedAt: When the entity was last updated
  • deletedAt: When the entity was marked as deleted (for soft deletes)
  • publishedAt: When the entity was published/made active

Implementation in Code

When implementing these naming conventions:

1. Update existing code during refactoring phases
2. Ensure all new code follows these conventions
3. Document any exceptions with clear rationale
4. Include naming convention verification in code reviews

Tools and Enforcement

• Use ESLint naming convention rules to enforce these standards
• Configure IDE settings to suggest correct naming patterns
• Include naming conventions in pull request templates

Exceptions

Any exceptions to these naming conventions must be:

1. Documented explicitly with rationale
2. Approved by the architecture team
3. Applied consistently within their specific context
4. Added to this document as an authorized exception