src/
├── [feature-module]/           # Feature-based organization
│   ├── [feature].types.ts     # Type definitions
│   ├── [feature].service.ts   # Business logic
│   ├── [feature].repository.ts # Data access
│   ├── [feature].controller.ts # Request handling
│   └── index.ts               # Public exports
├── shared/
│   ├── utils/
│   ├── hooks/
│   └── constants/
└── config/

// 1. Imports (external first, then internal)
// 2. Types/Interfaces
// 3. Constants
// 4. Utility functions (if small, related)
// 5. Main class/function
// 6. Helper functions (private)

// 1. IMPORTS
import { createUser, getUserById } from './user.repository';
import { UserError } from '@/shared/errors';

// 2. TYPES
interface UserCreateDto {
  name: string;
  email: string;
}

// 3. CONSTANTS
const MAX_NAME_LENGTH = 100;

// 4. UTILITIES (if small and related)
function validateEmail(email: string): boolean {
  return email.includes('@');
}

// 5. MAIN FUNCTION
export function createUser(dto: UserCreateDto): User {
  if (!validateEmail(dto.email)) {
    throw new UserError('Invalid email');
  }
  return createUser(dto);
}

// 6. HELPERS (private)
function sanitizeName(name: string): string {
  return name.trim().slice(0, MAX_NAME_LENGTH);
}

function processUser(user: User) {
  validateUser(user);     // Thing 1
  saveUser(user);         // Thing 2
  sendWelcomeEmail(user); // Thing 3
  logActivity(user);      // Thing 4
}

function createUser(dto: UserCreateDto): User {
  const user = validateAndSanitize(dto);
  return saveUser(user);
}

// Each function does ONE thing:
function validateAndSanitize(dto: UserCreateDto): User { /* ... */ }
function saveUser(user: User): User { /* ... */ }

// T001: Create todo model and repository
export class Todo { }

// T005: Implement todo creation
export function createTodo(dto: CreateTodoDto): Todo {
  // ...
}

// T010: Calculate todo priority based on due date
const priority = todo.dueDate
  ? calculatePriority(todo.dueDate)
  : Priority.LOW;

// Task References:
// T001 - Create todo model (spec: User Stories)
// T005 - Implement todo creation (spec: User Story 1)
// T010 - Priority calculation logic (spec: FR-003)

// TXXX: [Brief description of what this file contains]
// Description: [2-3 lines on purpose]
// Related: [spec reference or task ID]

// TXXX: [What this function does]
// Args: [parameter descriptions]
// Returns: [what it returns]
// Throws: [errors it may throw]

// TXXX: [Why this logic exists]
// The algorithm handles edge case X by doing Y
// Alternative approaches considered: [if relevant]

1. Identify refactoring need
2. Create or find task for refactoring
3. Ensure test coverage exists
4. Make small, verifiable changes
5. Run tests after each change
6. Commit with task ID

// BAD: Clever but unclear
const magic = (n) => !(~n + ~n + 1) << 2 >> n;

// BAD: One-liner at expense of clarity
const format = (d) => d.split('/').reverse().join('-');

// BAD: Nested ternary
const status = age < 18 ? 'minor' : age < 65 ? 'adult' : 'senior';

// GOOD: Clear intent
function isEven(n: number): boolean {
  return n % 2 === 0;
}

// GOOD: Intentional optimization with comment
// Using bitwise for performance in hot path (T010)
const isEvenFast = (n: number) => (n & 1) === 0;

// BAD: Abstract for "future" needs
interface ITodo<T extends Entity = Todo> extends IEntity, ITimestamped {}

// BAD: Factory for single use
class TodoFactoryFactory {
  static create(): TodoFactory<Todo> { return new TodoFactory(); }
}

// BAD: Interface for simple object
interface TodoConfig {
  color: string;
  theme: 'light' | 'dark';
}
const config: TodoConfig = { color: 'blue', theme: 'dark' };

// GOOD: Simple, direct
const config = { color: 'blue', theme: 'dark' as const };

// GOOD: Abstraction for actual variation
interface Repository<T> {
  findById(id: string): Promise<T>;
  save(entity: T): Promise<T>;
}

// No task ID - where did this come from?
function calculateComplexMetric(input: Input): number {
  // ... 100 lines of complex logic
}

// T015: Calculate user productivity score for dashboard
export function calculateProductivityScore(input: Input): number {
  // ... logic with T015 reference
}

// Use explicit types for function parameters
function createUser(name: string, email: string): User {
  return { name, email, createdAt: new Date() };
}

// Prefer interfaces for object shapes
interface CreateUserDto {
  name: string;
  email: string;
}

// Use type for unions/intersections
type UserStatus = 'active' | 'inactive' | 'pending';

// Avoid 'any' - use unknown if truly unknown
function handleError(error: unknown): void {
  if (error instanceof Error) {
    console.error(error.message);
  }
}

# Use type hints
def create_user(name: str, email: str) -> User:
    return User(name=name, email=email)

# Constants at module level
MAX_NAME_LENGTH = 100

# Docstrings for public functions
def calculate_metrics(data: list) -> dict:
    """
    Calculate summary metrics for data.

    Args:
        data: List of numeric values

    Returns:
        Dict with mean, median, and std dev
    """

// T001: User model and repository
// User entity definition with validation rules

interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

// T002: Email validation for user registration
export function isValidEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

// T003: Create new user from DTO
export function createUser(dto: CreateUserDto): User {
  if (!isValidEmail(dto.email)) {
    throw new ValidationError('Invalid email format');
  }
  return {
    id: generateId(),
    email: dto.email.trim().toLowerCase(),
    name: dto.name.trim(),
    createdAt: new Date(),
  };
}

// Task References:
// T001 - Create user model (spec: FR-001)
// T002 - Email validation (spec: FR-002)
// T003 - User creation (spec: FR-003)

// Bad: No task ID, unclear naming, magic number
function doStuff(x: any) {
  const arr = [];
  for (let i = 0; i < x.length; i++) {
    if (x[i] > 10) {
      arr.push(x[i] * 2);
    }
  }
  return arr;
}

// Refactored to good:
const MULTIPLIER = 2;
const THRESHOLD = 10;

// T010: Filter and transform values above threshold
export function filterAndDouble(values: number[]): number[] {
  return values
    .filter(value => value > THRESHOLD)
    .map(value => value * MULTIPLIER);
}