Software Engineering

Core Principles

Design

SOLID

Architecture

Presentation → Application → Domain ← Infrastructure
                    ↓
           Dependencies point DOWN only

Rules:

• Domain depends on nothing
• Infrastructure implements domain interfaces
• No circular dependencies

Design Patterns

Use when solving real problems, not preemptively:

Security

• Validate all external input (allowlists > denylists)
• Encrypt sensitive data at rest and transit
• Never log secrets
• Parameterized queries (SQL injection)
• Escape output (XSS)

Implementation

Naming

Rules:

• Names reveal intent
• No single-letter params
• No abbreviations (ur → userRepository)

Self-Documenting Code

// ❌ Comment hiding bad code
if (u.r === 1 && u.s !== 0) { ... }

// ✅ Self-documenting
if (user.isAdmin && user.isActive) { ... }

Acceptable comments: RFC links, bug tracker refs, non-obvious warnings

Functions

Error Handling

// ❌ Silent catch
try {
  await save(user);
} catch (e) {}

// ❌ Log only
try {
  await save(user);
} catch (e) {
  console.log(e);
}

// ✅ Let propagate or handle specific
try {
  await save(user);
} catch (e) {
  if (e instanceof DuplicateEmail) return { error: "Email taken" };
  throw e;
}

Rules:

• Empty catch = always wrong
• Catch only what you can handle
• Re-throw with context or propagate
• Crash visibly > fail silently

File Organization

• Match existing conventions
• No barrel files (index.ts re-exports)
• Import from concrete modules
• Co-locate tests with source

src/users/
  user-service.ts
  user-service.test.ts

Code Smells

Linting

Rules:

• Automate formatting
• Zero warnings in CI
• Never disable rules—fix the code

Testing

Test Pyramid

    E2E (few) - Critical journeys, slow
   Integration (some) - Component interactions
  Unit (many) - Fast, isolated, business logic

What to Test

Test Quality

• Independent and isolated
• Deterministic (no flakiness)
• Fast (< 100ms unit)
• Single reason to fail
• Test behavior, not implementation

BDD Structure

describe("UserService", () => {
  describe("given valid data", () => {
    describe("when creating user", () => {
      it("then persists with ID", async () => {
        // arrange, act, assert
      });
    });
  });
});

Anti-Patterns

Review

Before PR

• Type check passes
• Lint passes
• Tests pass
• No debug/console.log
• No commented code
• Up to date with main

Review Checklist

Correctness:

• Does it work? Edge cases? Error handling?

Design:

• Right abstraction? SOLID? Dependencies appropriate?

Readability:

• Clear names? Straightforward logic? No unnecessary comments?

Security:

• Input validated? No injection? Secrets handled?

Performance:

• No N+1? No await in loops? Caching considered?

Tests:

• Sufficient coverage? Edge cases? Behavior-focused?

For Reviewers

• Code, not author
• Questions > demands
• Explain the "why"
• Blocking vs nitpick

For Authors

• Small, focused PRs
• Context in description
• Respond to all comments

Maintenance

Refactoring

1. Ensure test coverage first
2. Small, incremental changes
3. Run tests after each change
4. Refactor OR add features, never both

Technical Debt

Find: unused code, duplicates, circular deps, outdated deps

Performance

1. Don't optimize prematurely
2. Measure before optimizing
3. Focus on hot paths

Documentation

Anti-Patterns