Coding Standards Configuration

// Variables: camelCase, noun-form
const userName = 'john';
const itemCount = 10;
const isActive = true;
 
// Functions: camelCase, verb-first
function getUserById(id: string) { }
function calculateTotal(items: Item[]) { }
function validateEmail(email: string) { }
 
// Constants: SCREAMING_SNAKE_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';

# Variables: snake_case, noun-form
user_name = 'john'
item_count = 10
is_active = True
 
# Functions: snake_case, verb-first
def get_user_by_id(user_id: str) -> User:
    pass
 
def calculate_total(items: list[Item]) -> float:
    pass
 
def validate_email(email: str) -> bool:
    pass
 
# Constants: SCREAMING_SNAKE_CASE
MAX_RETRY_COUNT = 3
API_BASE_URL = 'https://api.example.com'

// Variables: camelCase, noun-form
$userName = 'john';
$itemCount = 10;
$isActive = true;
 
// Methods: camelCase, verb-first
public function getUserById(string $id): User { }
public function calculateTotal(array $items): float { }
public function validateEmail(string $email): bool { }
 
// Constants: SCREAMING_SNAKE_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';

// Classes: PascalCase, noun
class UserService { }
class OrderRepository { }
 
// Interfaces: PascalCase, optional I prefix (per team convention)
interface User { }
interface IUserService { }  // optional style
 
// Types: PascalCase
type UserRole = 'admin' | 'user' | 'guest';
type ApiResponse<T> = { data: T; error?: string };

# Classes: PascalCase, noun
class UserService:
    pass
 
class OrderRepository:
    pass
 
# Protocols / Abstract classes: PascalCase
from typing import Protocol
 
class UserRepositoryProtocol(Protocol):
    def get_by_id(self, user_id: str) -> User: ...
 
# Type aliases: PascalCase
UserRole = Literal['admin', 'user', 'guest']

// Classes: PascalCase, noun
class UserService { }
class OrderRepository { }
 
// Interfaces: PascalCase, optional Interface suffix
interface UserRepositoryInterface { }
interface Authenticatable { }
 
// Traits: PascalCase
trait HasTimestamps { }
trait Notifiable { }

## Naming Conventions (TypeScript)
 
### File Naming
- Regular files: kebab-case.ts (e.g. user-service.ts)
- React components: PascalCase.tsx (e.g. UserProfile.tsx)
- Test files: *.test.ts or *.spec.ts
 
### Identifier Naming
- Variables/functions: camelCase (e.g. getUserById)
- Classes/interfaces/types: PascalCase (e.g. UserService)
- Constants: SCREAMING_SNAKE_CASE (e.g. MAX_RETRY)
- Booleans: is/has/can/should prefix (e.g. isActive)
 
### Naming Principles
- Variables are nouns, functions are verbs
- Names must be meaningful — avoid a, b, x, temp
- No abbreviations unless widely recognized (e.g. id, url)

## Naming Conventions (Python)
 
### File Naming
- Module files: snake_case.py (e.g. user_service.py)
- Test files: test_*.py or *_test.py
 
### Identifier Naming
- Variables/functions: snake_case (e.g. get_user_by_id)
- Classes: PascalCase (e.g. UserService)
- Constants: SCREAMING_SNAKE_CASE (e.g. MAX_RETRY)
- Private members: _leading_underscore (e.g. _internal_method)
- Booleans: is/has/can/should prefix (e.g. is_active)
 
### Naming Principles
- Follow PEP 8
- Variables are nouns, functions are verbs
- Avoid single-character names (except loop variables)

## Naming Conventions (PHP)
 
### File Naming
- Class files: PascalCase.php (e.g. UserService.php)
- Regular files: snake_case.php (e.g. helpers.php)
- Test files: *Test.php (e.g. UserServiceTest.php)
 
### Identifier Naming
- Variables: camelCase (e.g. $userName)
- Methods: camelCase (e.g. getUserById)
- Classes/interfaces/traits: PascalCase (e.g. UserService)
- Constants: SCREAMING_SNAKE_CASE (e.g. MAX_RETRY)
- Booleans: is/has/can/should prefix (e.g. $isActive)
 
### Naming Principles
- Follow PSR-12
- Class name must match file name
- Namespace must match directory structure

// ❌ Bad: one function doing multiple things
function processUser(user: User) {
  // validate
  if (!user.email) throw new Error('Invalid email');
  // save to database
  db.save(user);
  // send welcome email
  sendEmail(user.email, 'Welcome!');
  // log
  logger.info('User created');
}
 
// ✅ Good: each function does one thing
function validateUser(user: User): void {
  if (!user.email) throw new Error('Invalid email');
}
 
function saveUser(user: User): void {
  db.save(user);
}
 
function sendWelcomeEmail(email: string): void {
  sendEmail(email, 'Welcome!');
}
 
function createUser(user: User): void {
  validateUser(user);
  saveUser(user);
  sendWelcomeEmail(user.email);
  logger.info('User created');
}

# ❌ Bad: one function doing multiple things
def process_user(user: User) -> None:
    # validate
    if not user.email:
        raise ValueError('Invalid email')
    # save to database
    db.save(user)
    # send welcome email
    send_email(user.email, 'Welcome!')
    # log
    logger.info('User created')
 
# ✅ Good: each function does one thing
def validate_user(user: User) -> None:
    if not user.email:
        raise ValueError('Invalid email')
 
def save_user(user: User) -> None:
    db.save(user)
 
def send_welcome_email(email: str) -> None:
    send_email(email, 'Welcome!')
 
def create_user(user: User) -> None:
    validate_user(user)
    save_user(user)
    send_welcome_email(user.email)
    logger.info('User created')

// ❌ Bad: one function doing multiple things
public function processUser(User $user): void {
    // validate
    if (!$user->email) throw new Exception('Invalid email');
    // save to database
    $this->db->save($user);
    // send welcome email
    $this->sendEmail($user->email, 'Welcome!');
    // log
    $this->logger->info('User created');
}
 
// ✅ Good: each function does one thing
public function validateUser(User $user): void {
    if (!$user->email) throw new InvalidArgumentException('Invalid email');
}
 
public function saveUser(User $user): void {
    $this->db->save($user);
}
 
public function sendWelcomeEmail(string $email): void {
    $this->sendEmail($email, 'Welcome!');
}
 
public function createUser(User $user): void {
    $this->validateUser($user);
    $this->saveUser($user);
    $this->sendWelcomeEmail($user->email);
    $this->logger->info('User created');
}

// ❌ Bad: too many parameters
function createUser(
  name: string,
  email: string,
  age: number,
  address: string,
  phone: string,
  role: string
) { }
 
// ✅ Good: use object parameter
interface CreateUserParams {
  name: string;
  email: string;
  age: number;
  address: string;
  phone: string;
  role: string;
}
 
function createUser(params: CreateUserParams) { }

# ❌ Bad: too many parameters
def create_user(
    name: str,
    email: str,
    age: int,
    address: str,
    phone: str,
    role: str
) -> User:
    pass
 
# ✅ Good: use dataclass
@dataclass
class CreateUserParams:
    name: str
    email: str
    age: int
    address: str
    phone: str
    role: str
 
def create_user(params: CreateUserParams) -> User:
    pass

// ❌ Bad: too many parameters
public function createUser(
    string $name,
    string $email,
    int $age,
    string $address,
    string $phone,
    string $role
): User { }
 
// ✅ Good: use DTO
class CreateUserDto {
    public function __construct(
        public string $name,
        public string $email,
        public int $age,
        public string $address,
        public string $phone,
        public string $role,
    ) {}
}
 
public function createUser(CreateUserDto $dto): User { }

// ✅ Explicit return type
function getUserById(id: string): User | null {
  const user = db.find(id);
  return user ?? null;
}
 
// ✅ Result pattern for error handling
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
 
function parseJson(str: string): Result<unknown, Error> {
  try {
    return { ok: true, value: JSON.parse(str) };
  } catch (e) {
    return { ok: false, error: e as Error };
  }
}

from typing import Optional
 
# ✅ Explicit return type
def get_user_by_id(user_id: str) -> Optional[User]:
    user = db.find(user_id)
    return user if user else None
 
# ✅ Result pattern (or return tuple)
from dataclasses import dataclass
from typing import Generic, TypeVar, Union
 
T = TypeVar('T')
E = TypeVar('E')
 
@dataclass
class Ok(Generic[T]):
    value: T
 
@dataclass
class Err(Generic[E]):
    error: E
 
Result = Union[Ok[T], Err[E]]
 
def parse_json(s: str) -> Result[dict, str]:
    try:
        return Ok(json.loads(s))
    except json.JSONDecodeError as e:
        return Err(str(e))

// ✅ Explicit return type (PHP 8+)
public function getUserById(string $id): ?User {
    $user = $this->db->find($id);
    return $user ?? null;
}
 
// ✅ Result pattern
class Result {
    private function __construct(
        public readonly bool $ok,
        public readonly mixed $value = null,
        public readonly ?string $error = null,
    ) {}
 
    public static function ok(mixed $value): self {
        return new self(true, $value);
    }
 
    public static function err(string $error): self {
        return new self(false, error: $error);
    }
}
 
public function parseJson(string $str): Result {
    try {
        return Result::ok(json_decode($str, true, flags: JSON_THROW_ON_ERROR));
    } catch (JsonException $e) {
        return Result::err($e->getMessage());
    }
}

// ✅ Optional chaining
const userName = user?.profile?.name;
 
// ✅ Nullish coalescing
const displayName = userName ?? 'Anonymous';
 
// ✅ Early return to avoid deep nesting
function getDisplayName(user: User | null): string {
  if (!user) return 'Anonymous';
  if (!user.profile) return user.email;
  return user.profile.name ?? user.email;
}

from typing import Optional
 
# ✅ Use Optional type annotation
def get_user_name(user: Optional[User]) -> str:
    if user is None:
        return 'Anonymous'
    return user.name or 'Anonymous'
 
# ✅ Use or to provide a default
display_name = user_name or 'Anonymous'
 
# ✅ getattr with default
name = getattr(user, 'name', 'Anonymous')

// ✅ Nullsafe operator
$userName = $user?->profile?->name;
 
// ✅ Null coalescing assignment
$displayName = $userName ?? 'Anonymous';
 
// ✅ Early return
public function getDisplayName(?User $user): string {
    if ($user === null) return 'Anonymous';
    if ($user->profile === null) return $user->email;
    return $user->profile->name ?? $user->email;
}

## Error Handling (TypeScript)
 
### Type Safety
- Never use any — use unknown in catch blocks
- Use type guards to validate error types
- Custom error classes extend Error
 
### Error Handling Principles
- Never swallow exceptions (empty catch blocks)
- Caught exceptions must be logged or re-thrown
- Error messages must include context
 
### Null Handling
- Use optional chaining (?.) for potentially null properties
- Use nullish coalescing (??) to provide defaults
- Explicitly check null/undefined — don't rely on implicit coercion

## Error Handling (Python)
 
### Exception Handling
- Never use bare except
- Catch specific exception types
- Use raise from to preserve exception chains
 
### Custom Exceptions
- Inherit from the appropriate built-in exception
- Include meaningful error messages and context
- Follow exception naming conventions (*Error or *Exception)
 
### Null Handling
- Use Optional type annotations
- Use `is None` not `== None`
- Use the or operator to provide defaults

## Error Handling (PHP)
 
### Exception Handling
- Never use the @ error suppressor
- Catch specific exception types
- Use the previous parameter to preserve exception chains
 
### Custom Exceptions
- Build a project exception hierarchy
- Exceptions include error codes and context
- Follow PSR conventions
 
### Null Handling
- Use the ?-> nullsafe operator (PHP 8+)
- Use the ?? null coalescing operator
- Use nullable types for parameters and return values

// 1. External packages (node_modules)
import express from 'express';
import { z } from 'zod';
 
// 2. Internal modules (absolute paths)
import { UserService } from '@/services/user';
import { logger } from '@/utils/logger';
 
// 3. Relative paths
import { validateUser } from './validators';
import type { User } from './types';

# 1. Standard library
import os
import sys
from datetime import datetime
 
# 2. Third-party packages
import requests
from pydantic import BaseModel
 
# 3. Local modules
from app.services.user import UserService
from app.utils.logger import logger
 
from .validators import validate_user
from .types import User

<?php
 
// Strict type declaration
declare(strict_types=1);
 
namespace App\Services;
 
// use statements sorted alphabetically
use App\Exceptions\ApiException;
use App\Models\User;
use App\Repositories\UserRepository;
use Psr\Log\LoggerInterface;
 
class UserService
{
    // ...
}

/**
 * Retrieve a user by their ID
 *
 * @param id - The unique user identifier
 * @returns The user object, or null if not found
 * @throws {ApiError} When the database connection fails
 *
 * @example
 * ```ts
 * const user = await getUserById('123');
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 */
async function getUserById(id: string): Promise<User | null> {
  // ...
}

def get_user_by_id(user_id: str) -> Optional[User]:
    """Retrieve a user by their ID
 
    Args:
        user_id: The unique user identifier
 
    Returns:
        The user object, or None if not found
 
    Raises:
        ApiError: When the database connection fails
 
    Example:
        >>> user = get_user_by_id('123')
        >>> if user:
        ...     print(user.name)
    """
    # ...

/**
 * Retrieve a user by their ID
 *
 * @param string $id The unique user identifier
 * @return User|null The user object, or null if not found
 * @throws ApiException When the database connection fails
 *
 * @example
 * $user = $this->getUserById('123');
 * if ($user !== null) {
 *     echo $user->getName();
 * }
 */
public function getUserById(string $id): ?User
{
    // ...
}