Coding Conventions

In This Document

• In This Document
• Naming Conventions
  • General Naming Rules
  • PHP Naming Conventions
  • JavaScript/TypeScript Naming Conventions
  • Database Naming Conventions
• File Organization
  • Directory Structure
  • File Placement Rules
• Code Style
• Documentation Standards
  • Code Comments
  • README Files
• Agreed Exceptions
• Enforcement

Naming Conventions

General Rules

General Naming Rules

• Use descriptive names that clearly convey purpose
• Avoid abbreviations except for widely accepted ones (e.g., ID, HTTP)
• Keep names concise but not at the expense of clarity
• Be consistent with existing codebase patterns

tip

If you're spending more than a minute thinking about a name, it's probably too complex. Consider refactoring or breaking down the component.

PHP

PHP Naming Conventions

• Classes: PascalCase (e.g., UserRepository, PaymentService)
• Methods: camelCase (e.g., getUserById(), processPayment())
• Properties: camelCase (e.g., $userName, $paymentAmount)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_LOGIN_ATTEMPTS, API_VERSION)
• Namespaces: PascalCase (e.g., App\Services\Payment)

Models

• Singular noun (e.g., User, not Users)
• No prefixes or suffixes (e.g., Product, not ProductModel)

Controllers

• Suffix with Controller (e.g., UserController)
• Resource controllers should use plural nouns (e.g., ProductsController)

Repositories

• Suffix with Repository (e.g., UserRepository)

JavaScript/TypeScript

JavaScript/TypeScript Naming Conventions

• Variables: camelCase (e.g., userName, paymentAmount)
• Functions: camelCase (e.g., getUserData(), calculateTotal())
• Classes: PascalCase (e.g., UserService, PaymentProcessor)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRY_COUNT, DEFAULT_TIMEOUT)
• Private properties: Prefix with underscore (e.g., _privateData)
• Component files: PascalCase (e.g., UserProfile.vue, PaymentForm.jsx)
• Non-component files: camelCase (e.g., apiService.js, formUtils.ts)

Database

Database Naming Conventions

• Tables: snake_case, plural (e.g., users, order_items)
• Columns: snake_case (e.g., first_name, created_at)
• Primary keys: id (singular)
• Foreign keys: Singular table name + _id (e.g., user_id, product_id)
• Pivot tables: Singular table names in alphabetical order (e.g., product_user)
• Indexes: idx_[table]_[column(s)] (e.g., idx_users_email)
• Unique constraints: unq_[table]_[column(s)] (e.g., unq_users_email)

File Organization

Directory Structure

Our agreed directory structure follows these conventions:

app/
├── Console/            # Console commands
├── Contracts/          # Interfaces
├── Events/             # Event classes
├── Exceptions/         # Custom exceptions
├── Http/
│   ├── Controllers/    # Controllers grouped by domain
│   ├── Middleware/     # HTTP middleware
│   └── Requests/       # Form requests
├── Jobs/               # Queue jobs
├── Listeners/          # Event listeners
├── Models/             # Eloquent models
├── Policies/           # Authorization policies
├── Providers/          # Service providers
├── Repositories/       # Repository pattern implementations
├── Services/           # Business logic services
└── Utilities/          # Helper classes and functions

note

New directories should be discussed with the team before creation to maintain consistency.

File Placement Rules

• Each class should be in its own file
• File name should match the class name exactly
• Related files should be grouped in subdirectories by domain/feature
• Test files should mirror the structure of the application code

Code Style

Our team follows the PSR-12 coding style for PHP with some additional agreements:

• Maximum line length: 100 characters
• Indent using 4 spaces (not tabs)
• Always use curly braces for control structures, even for single-line statements
• Add trailing commas in multiline arrays
• Order class elements: constants, properties, constructor, public methods, protected methods, private methods

Documentation Standards

Code Comments

• Document "why" not "what" (the code should be self-explanatory)
• Add PHPDoc/JSDoc comments for all public methods and classes
• Include parameter and return type documentation
• Document exceptions that may be thrown
• Keep comments up to date when code changes

README Files

Each major component should have a README.md file that includes:

• Purpose of the component
• Installation/setup instructions
• Usage examples
• Dependencies
• Common issues and solutions

Agreed Exceptions

While we strive to follow these conventions consistently, we've agreed on these exceptions:

• Legacy code may not follow these conventions until refactored
• Third-party integrations may require deviations from naming conventions
• Performance-critical code may prioritize optimization over strict adherence to conventions

Enforcement

These conventions are enforced through:

• Code reviews
• Automated linting tools
• Pair programming sessions
• Regular code quality discussions