❌ MULTIPLE RESPONSIBILITIES         ✅ SINGLE RESPONSIBILITY
─────────────────────────────────────────────────────
function processUser(user) {         function validateUser(user) { }
  validate(user);                    function saveUser(user) { }
  save(user);                        function sendWelcomeEmail(user) { }
  sendEmail(user);                   function logUserCreation(user) { }
  logActivity(user);
}                                    // Compose in caller

// ❌ FEATURE FLAGS: Hidden complexity
if (featureFlags.newCheckout) {
  await newCheckoutFlow(cart);
} else {
  await legacyCheckoutFlow(cart);
}

// ✅ SIMPLE: One code path
await checkoutFlow(cart);

┌─────────────────────────────────────────────────────┐
│         Presentation Layer                          │  UI, API Controllers
├─────────────────────────────────────────────────────┤
│         Application Layer                           │  Use Cases, Orchestration
├─────────────────────────────────────────────────────┤
│           Domain Layer                              │  Business Logic, Entities
├─────────────────────────────────────────────────────┤
│        Infrastructure Layer                         │  Database, External Services
└─────────────────────────────────────────────────────┘

Rule: Dependencies point downward only

✅ GOOD                              ❌ BAD
─────────────────────────────────────────────────────
Domain → nothing                     Domain → Infrastructure
Application → Domain                 UI → Database directly
Infrastructure → Domain              Circular dependencies

❌ BAD: Comment explaining unclear code
// Check if user can access the resource
if (u.r === 1 && u.s !== 0 && checkTs(u.t)) { ... }

✅ GOOD: Self-documenting code needs no comment
if (user.isAdmin && user.isActive && !user.isSessionExpired()) { ... }

❌ INLINE COMMENTS (Don't write these)
─────────────────────────────────────────────────────
// Increment i
// Loop through array
// Set x to 5
// This function does stuff
// Added by John on 2024-01-15
// Get the user
// Check if valid
// Return the result
// TODO: Fix this later (track in issue tracker instead)
// FIXME: This is broken (fix it now or create an issue)

✅ ACCEPTABLE COMMENTS (Rare exceptions)
─────────────────────────────────────────────────────
// See RFC 7231 Section 6.5.4 for status code semantics
// Workaround for browser bug https://bugs.webkit.org/12345
// WARNING: This mutates the input array for performance

✅ GOOD                              ❌ BAD
─────────────────────────────────────────────────────
getUserById(userId)                  get(id)
isValidEmail(email)                  check(email)
calculateTotalPrice(items)           calc(items)
MAX_RETRY_ATTEMPTS                   MAX
userRepository                       ur
fetchUserData()                      getData()
hasPermission(user, action)          perm(u, a)
activeUsers                          list
emailAddress                         str
retryCount                           n
isEnabled                            flag
createdAt                            date

❌ BAD: Ambiguous parameters
function process(x) { ... }
function calc(a, b, c) { ... }
const result = items.map(x => x.value);

✅ GOOD: Clear, descriptive parameters
function processOrder(order) { ... }
function calculateDiscount(price, quantity, discountRate) { ... }
const values = items.map(item => item.value);

✅ CONSISTENT FILE NAMING
─────────────────────────────────────────────────────
kebab-case (recommended for most projects):
  user-service.ts
  order-repository.ts
  api-client.test.ts

PascalCase (React components, classes):
  UserProfile.tsx
  OrderList.tsx

snake_case (Python, Ruby):
  user_service.py
  order_repository.py

ALWAYS match existing project conventions!

✅ GOOD STRUCTURE                    ❌ BAD STRUCTURE
─────────────────────────────────────────────────────
src/                                 src/
  users/                               utils.ts (god file)
    user-service.ts                    helpers.ts (vague)
    user-repository.ts                 misc.ts (dumping ground)
    user.types.ts                      stuff.ts (meaningless)
    user-service.test.ts               file1.ts (lazy naming)
  orders/
    order-service.ts
    order-repository.ts

❌ DON'T: Introduce inconsistent patterns
// Existing: userService.getById(id)
// New code: fetchSingleOrder(orderId)  // Different naming style!

✅ DO: Match existing conventions
// Existing: userService.getById(id)
// New code: orderService.getById(orderId)  // Consistent!

❌ BAD: Barrel file
// src/users/index.ts
export * from "./user-service";
export * from "./user-repository";

// usage
import { userService } from "./users";

✅ GOOD: Direct imports
import { userService } from "./users/user-service";
import { userRepository } from "./users/user-repository";

✅ BEST PRACTICES                    ❌ ANTI-PATTERNS
─────────────────────────────────────────────────────
Small, focused functions             God functions (100+ lines)
2-3 parameters max                   6+ parameters
Return early for edge cases          Deep nesting
Pure functions when possible         Hidden side effects
Descriptive names                    Abbreviations
Single level of abstraction          Mixed abstraction levels

✅ DO                                ❌ DON'T
─────────────────────────────────────────────────────
Fail fast and loud                   Swallow exceptions silently
Use specific exception types         Catch generic Exception
Include context in error messages    Return null for errors
Validate inputs at boundaries        Trust external data
Log errors with stack traces         Log without context
Use Result/Either types              Return magic values (-1, null)
Handle errors at appropriate level   Handle everywhere or nowhere
Let unexpected errors propagate      Catch everything "just in case"

// ❌ NEVER: Silent catch
try {
  await saveUser(user);
} catch (error) {
  // silently ignored
}

// ❌ NEVER: Catch and log only (still loses the error)
try {
  await saveUser(user);
} catch (error) {
  console.log(error);
}

// ✅ GOOD: Let it propagate (caller handles or app crashes visibly)
await saveUser(user);

// ✅ GOOD: Handle specific errors you can recover from
try {
  await saveUser(user);
} catch (error) {
  if (error instanceof DuplicateEmailError) {
    return { error: "Email already registered" };
  }
  throw error; // Re-throw unexpected errors
}

// ✅ GOOD: Add context and re-throw
try {
  await saveUser(user);
} catch (error) {
  throw new UserServiceError(`Failed to save user ${user.id}`, {
    cause: error,
  });
}

// ✅ Result type pattern
type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

function parseConfig(path: string): Result<Config> {
  try {
    const data = readFile(path);
    return { ok: true, value: JSON.parse(data) };
  } catch (error) {
    return { ok: false, error: new ConfigError(`Invalid config: ${path}`) };
  }
}

// ✅ Early return pattern
function processUser(user: User | null): string {
  if (!user) return "No user";
  if (!user.isActive) return "User inactive";
  if (!user.hasPermission) return "No permission";

  return performAction(user); // Happy path
}

// ❌ NEVER: Disable type safety - write proper types instead
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const response: any = await legacyApi.fetch();

// ✅ CORRECT: Write types for untyped APIs
interface LegacyResponse {
  data: unknown;
  status: number;
}
const response: LegacyResponse = await legacyApi.fetch();

        /\
       /  \     E2E Tests (few)
      /----\    - Critical user journeys
     /      \   - Slow, expensive
    /--------\
   /          \ Integration Tests (some)
  /------------\- Component interactions
 /              \- Database, APIs
/----------------\
   Unit Tests (many)
   - Fast, isolated
   - Business logic

✅ TEST                              ❌ SKIP
─────────────────────────────────────────────────────
Business logic                       Framework code
Edge cases and boundaries            Trivial getters/setters
Error handling paths                 Third-party libraries
Public API contracts                 Private implementation details
Integration points                   UI layout (use visual tests)
Security-sensitive code              Configuration files

Business Need → Executable Specification → Working Software

❌ BAD: Implementation details, unclear intent
─────────────────────────────────────────────────────
"open browser, navigate to /login, find element with
id email, type test@test.com, click submit button"

✅ GOOD: Business language, clear intent
─────────────────────────────────────────────────────
Given a registered user exists
When the user logs in with valid credentials
Then the user should see their dashboard

✅ DO                                ❌ DON'T
─────────────────────────────────────────────────────
Write from user's perspective        Use technical jargon
One behavior per scenario            Test multiple things
Use declarative style                Include implementation details
Keep scenarios independent           Share state between scenarios
Use meaningful data                  Use "test", "foo", "bar"
Focus on business outcomes           Focus on UI interactions

describe("UserService", () => {
  describe("given a new user with valid data", () => {
    const userData = { name: "Alice", email: "alice@example.com" };

    describe("when creating the user", () => {
      it("then the user should be created with an ID", async () => {
        const userService = new UserService();
        const user = await userService.create(userData);

        expect(user.id).toBeDefined();
        expect(user.name).toBe("Alice");
        expect(user.email).toBe("alice@example.com");
      });
    });
  });

  describe("given user data with an invalid email", () => {
    const userData = { name: "Bob", email: "invalid-email" };

    describe("when creating the user", () => {
      it("then it should reject with a validation error", async () => {
        const userService = new UserService();

        await expect(userService.create(userData)).rejects.toThrow(
          "Invalid email",
        );
      });
    });
  });
});

describe("User Login", () => {
  describe("given a registered user exists", () => {
    let user: User;

    beforeEach(async () => {
      user = await createUser({
        email: "alice@example.com",
        password: "secure123",
      });
    });

    describe("when the user logs in with valid credentials", () => {
      let session: Session;

      beforeEach(async () => {
        session = await login(user.email, "secure123");
      });

      it("then a valid session should be created", () => {
        expect(session.token).toBeDefined();
        expect(session.userId).toBe(user.id);
      });

      it("then the user should be able to access their dashboard", async () => {
        const dashboard = await getDashboard(session);

        expect(dashboard.userId).toBe(user.id);
        expect(dashboard.welcomeMessage).toContain(user.name);
      });
    });

    describe("when the user logs in with wrong password", () => {
      it("then login should fail with authentication error", async () => {
        await expect(login(user.email, "wrongpassword")).rejects.toThrow(
          "Invalid credentials",
        );
      });
    });
  });
});

describe("User Processing", () => {
  describe("given a null user input", () => {
    describe("when processing the user", () => {
      it("then it should throw a validation error", () => {
        expect(() => processUser(null)).toThrow("User cannot be null");
      });
    });
  });

  describe("given an invalid user ID", () => {
    describe("when fetching the user", () => {
      it("then it should throw a ValidationError", async () => {
        await expect(fetchUser(-1)).rejects.toBeInstanceOf(ValidationError);
      });

      it("then the error should include the invalid ID", async () => {
        await expect(fetchUser(-1)).rejects.toThrow(/invalid user id.*-1/i);
      });
    });
  });
});

describe("Order Discount Calculation", () => {
  describe("given different order totals", () => {
    const testCases = [
      { orderTotal: 50, expectedDiscount: 0, scenario: "order under $100" },
      { orderTotal: 100, expectedDiscount: 10, scenario: "order exactly $100" },
      {
        orderTotal: 250,
        expectedDiscount: 25,
        scenario: "order between $100-$500",
      },
      { orderTotal: 500, expectedDiscount: 75, scenario: "order exactly $500" },
      { orderTotal: 1000, expectedDiscount: 150, scenario: "order over $500" },
    ];

    testCases.forEach(({ orderTotal, expectedDiscount, scenario }) => {
      describe(`given an ${scenario} ($${orderTotal})`, () => {
        describe("when calculating the discount", () => {
          it(`then the discount should be $${expectedDiscount}`, () => {
            const discount = calculateDiscount(orderTotal);
            expect(discount).toBe(expectedDiscount);
          });
        });
      });
    });
  });
});

src/
  users/
    user-service.ts
    user-service.test.ts    # Co-located tests
  orders/
    order-service.ts
    order-service.test.ts

undefined

// ❌ BAD: Vague names, no context
it("works", () => {});
it("handles error", () => {});
it("test1", () => {});

// ❌ BAD: Missing Given-When-Then structure
describe("UserService", () => {
  it("creates user", () => {});
  it("throws on invalid email", () => {});
});

// ✅ GOOD: Full BDD structure with Given-When-Then
describe("UserService", () => {
  describe("given valid user data", () => {
    describe("when creating a user", () => {
      it("then the user should be persisted with an ID", () => {});
    });
  });

  describe("given an invalid email format", () => {
    describe("when creating a user", () => {
      it("then a ValidationError should be thrown", () => {});
    });
  });
});

✅ DOCUMENT                          ❌ SKIP
─────────────────────────────────────────────────────
Public APIs                          Obvious code
Architecture decisions (ADRs)        Implementation details
Setup and deployment                 Every function
Non-obvious behavior                 Self-documenting code
Known limitations                    Temporary hacks (fix them)

"Make it work, make it right, make it fast" - Kent Beck
"Any fool can write code that a computer can understand.
 Good programmers write code that humans can understand." - Martin Fowler
"Simplicity is the ultimate sophistication" - Leonardo da Vinci
"The best code is no code at all" - Jeff Atwood