Best Practices and Patterns

The Code Review That Saved Our SaaS

Thursday 4:15 PM, quarterly review. Our CTO reviewing pull requests from the last 3 months: 347 PRs merged.

He stopped at PR #183: "Who approved this?"

// The offending code
function processPayment(data: any): any {
  const amount = data.amount;
  const userId = data.userId;
  return chargeCard(amount, userId);
}

"This went to production?"

It did. And it caused the May 12th incident: $47,000 in failed payments because data.userId was sometimes a number, sometimes a string, and our payment processor expected strings.

CTO's decree: "We need standards. Now."

I was tasked with creating our TypeScript Best Practices Guide. Two weeks of research. Analysis of 200,000+ lines of our production code. Interviews with every senior dev.

Result: A checklist that catches 90% of issues before code review. Our bug rate dropped 61% in the next quarter.

Here's everything we learned.

---

Project Structure

Recommended Organization

src/
├── types/              # Type definitions
│   ├── user.ts
│   ├── product.ts
│   └── order.ts
├── models/             # Data models/classes
│   ├── User.ts
│   ├── Product.ts
│   └── Order.ts
├── services/           # Business logic
│   ├── userService.ts
│   ├── productService.ts
│   └── orderService.ts
├── controllers/        # API controllers
│   ├── userController.ts
│   ├── productController.ts
│   └── orderController.ts
├── utils/              # Helper functions
│   ├── validation.ts
│   ├── formatting.ts
│   └── encryption.ts
├── middleware/         # Express middleware
│   ├── auth.ts
│   ├── errorHandler.ts
│   └── requestLogger.ts
├── config/             # Configuration
│   ├── database.ts
│   ├── server.ts
│   └── constants.ts
└── index.ts            # Entry point

File Naming

// ✓ Good - PascalCase for classes
class UserService {}        // UserService.ts

// ✓ Good - camelCase for functions/utils
export function formatDate() {}  // formatDate.ts

// ✓ Good - kebab-case for multi-word files
// user-repository.ts
// payment-processor.ts

// ✗ Bad - inconsistent
// UserService.ts, userservice.ts, user_service.ts all in same project

---

Naming Conventions

Interfaces vs Types

// ✓ Prefer interfaces for object shapes
interface User {
  id: string;
  name: string;
}

// ✓ Use types for unions, intersections, primitives
type Status = 'active' | 'inactive' | 'pending';
type ID = string | number;
type UserWithTimestamp = User & { timestamp: Date };

// ✗ Don't prefix with "I"
interface IUser {}  // Bad - no need for "I" prefix in TypeScript

Variables and Functions

// ✓ Good - descriptive, intention-revealing
const userEmailAddress = '[email protected]';
function calculateTotalOrderPrice(items: CartItem[]): number {}

// ✗ Bad - abbreviations, single letters
const e = '[email protected]';
function calc(i: any): number {}

// ✓ Booleans - use is/has/should prefix
const isAuthenticated = true;
const hasPermission = checkPermission();
const shouldShowModal = false;

// ✓ Arrays - plural nouns
const users = ['John', 'Jane'];
const products = await fetchProducts();

// ✓ Functions - verb + noun
function getUserById(id: string): User {}
function deleteProduct(productId: string): void {}
function validateEmail(email: string): boolean {}

---

Type Safety Best Practices

Rule 1: Never Use any

// ✗ Bad - defeats TypeScript
function processData(data: any): any {
  return data.value;
}

// ✓ Good - use unknown for truly unknown data
function processData(data: unknown): number {
  if (typeof data === 'object' && data !== null && 'value' in data) {
    const obj = data as { value: unknown };
    if (typeof obj.value === 'number') {
      return obj.value;
    }
  }
  throw new Error('Invalid data');
}

// ✓ Better - define proper types
interface DataStructure {
  value: number;
  label: string;
}

function processData(data: DataStructure): number {
  return data.value;
}

Rule 2: Strict Null Checks

// Enable in tsconfig.json
{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

// ✓ Good - handle null explicitly
function findUser(id: string): User | null {
  const user = database.find(id);
  return user || null;
}

const user = findUser('123');
if (user) {
  console.log(user.name);  // Safe
}

// ✗ Bad - assuming non-null
function findUser(id: string): User {
  return database.find(id);  // Might be null!
}

Rule 3: Use Type Guards

// ✓ Good - proper type narrowing
function processValue(value: string | number) {
  if (typeof value === 'string') {
    return value.toUpperCase();  // TypeScript knows it's string
  }
  return value.toFixed(2);  // TypeScript knows it's number
}

// ✓ Custom type guards
interface Dog {
  breed: string;
  bark(): void;
}

interface Cat {
  color: string;
  meow(): void;
}

function isDog(animal: Dog | Cat): animal is Dog {
  return (animal as Dog).bark !== undefined;
}

function handleAnimal(animal: Dog | Cat) {
  if (isDog(animal)) {
    animal.bark();  // TypeScript knows it's Dog
  } else {
    animal.meow();  // TypeScript knows it's Cat
  }
}

---

Function Best Practices

Explicit Return Types

// ✓ Good - explicit return type
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// ✗ Bad - inferred return (harder to catch errors)
function calculateTotal(items: CartItem[]) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// Why? Prevents accidental returns:
function findUser(id: string): User | null {  // ← Forces you to handle null
  const user = database.find(id);
  return user;  // Type error if database.find returns undefined instead of null
}

Avoid Optional Parameters Hell

// ✗ Bad - too many optional params
function createUser(
  name: string,
  email?: string,
  age?: number,
  phone?: string,
  address?: string
) {}

// ✓ Good - use options object
interface CreateUserOptions {
  name: string;
  email?: string;
  age?: number;
  phone?: string;
  address?: string;
}

function createUser(options: CreateUserOptions) {
  // ...
}

// Usage - clear and maintainable
createUser({
  name: 'John',
  email: '[email protected]',
  age: 30
});

---

Error Handling

Custom Error Classes

// ✓ Good - typed errors
class AppError extends Error {
  constructor(
    public statusCode: number,
    public message: string,
    public isOperational = true
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
  }
}

class NotFoundError extends AppError {
  constructor(message: string) {
    super(404, message);
  }
}

class ValidationError extends AppError {
  constructor(message: string) {
    super(400, message);
  }
}

// Usage
function getUser(id: string): User {
  const user = database.find(id);
  if (!user) {
    throw new NotFoundError(`User ${id} not found`);
  }
  return user;
}

Result Type Pattern

// ✓ Alternative - no exceptions
type Result<T, E = Error> = 
  | { success: true; value: T }
  | { success: false; error: E };

function divideNumbers(a: number, b: number): Result<number> {
  if (b === 0) {
    return { success: false, error: new Error('Division by zero') };
  }
  return { success: true, value: a / b };
}

// Usage
const result = divideNumbers(10, 2);
if (result.success) {
  console.log(result.value);  // TypeScript knows value exists
} else {
  console.error(result.error);  // TypeScript knows error exists
}

---

Async/Await Best Practices

// ✓ Good - proper async error handling
async function fetchUserData(userId: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${userId}`);
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    const data: User = await response.json();
    return data;
  } catch (error) {
    if (error instanceof Error) {
      throw new AppError(500, `Failed to fetch user: ${error.message}`);
    }
    throw new AppError(500, 'Unknown error occurred');
  }
}

// ✓ Parallel async operations
async function getUserDashboard(userId: string) {
  const [user, orders, notifications] = await Promise.all([
    fetchUser(userId),
    fetchOrders(userId),
    fetchNotifications(userId)
  ]);
  
  return { user, orders, notifications };
}

---

Linting with ESLint

Installation

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Configuration

// .eslintrc.json
{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module"
  },
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-non-null-assertion": "warn"
  }
}

---

Formatting with Prettier

npm install --save-dev prettier

// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2
}

---

Common Patterns

1. Builder Pattern

class UserBuilder {
  private user: Partial<User> = {};
  
  setName(name: string): this {
    this.user.name = name;
    return this;
  }
  
  setEmail(email: string): this {
    this.user.email = email;
    return this;
  }
  
  setAge(age: number): this {
    this.user.age = age;
    return this;
  }
  
  build(): User {
    if (!this.user.name || !this.user.email) {
      throw new Error('Name and email required');
    }
    return this.user as User;
  }
}

// Usage
const user = new UserBuilder()
  .setName('John')
  .setEmail('[email protected]')
  .setAge(30)
  .build();

2. Factory Pattern

interface Logger {
  log(message: string): void;
}

class ConsoleLogger implements Logger {
  log(message: string) {
    console.log(message);
  }
}

class FileLogger implements Logger {
  log(message: string) {
    // Write to file
  }
}

class LoggerFactory {
  static createLogger(type: 'console' | 'file'): Logger {
    switch (type) {
      case 'console':
        return new ConsoleLogger();
      case 'file':
        return new FileLogger();
    }
  }
}

const logger = LoggerFactory.createLogger('console');
logger.log('Hello');

3. Repository Pattern

interface Repository<T> {
  findById(id: string): Promise<T | null>;
  findAll(): Promise<T[]>;
  create(item: Omit<T, 'id'>): Promise<T>;
  update(id: string, item: Partial<T>): Promise<T | null>;
  delete(id: string): Promise<boolean>;
}

class UserRepository implements Repository<User> {
  async findById(id: string): Promise<User | null> {
    return database.users.findOne({ id });
  }
  
  async findAll(): Promise<User[]> {
    return database.users.find();
  }
  
  async create(userData: Omit<User, 'id'>): Promise<User> {
    const id = generateId();
    return database.users.insert({ id, ...userData });
  }
  
  async update(id: string, updates: Partial<User>): Promise<User | null> {
    return database.users.updateOne({ id }, updates);
  }
  
  async delete(id: string): Promise<boolean> {
    const result = await database.users.deleteOne({ id });
    return result.deletedCount > 0;
  }
}

---

Code Review Checklist

Our 90% bug-catch checklist:

Type Safety

• No any types (use unknown if necessary)

• Explicit return types on functions

• Strict null checks enabled

• Type guards for union types

• Proper error handling

Naming

• Descriptive variable names

• Boolean variables use is/has/should prefix

• Functions use verb + noun

• Interfaces don't have "I" prefix

Structure

• One responsibility per function

• Functions under 50 lines

• Files under 300 lines

• No circular dependencies

Testing

• Unit tests for business logic

• Type tests for complex types

• Error cases covered

Documentation

• Complex logic has comments

• Public APIs have JSDoc

• README updated if needed

---

Your Challenge

Refactor bad TypeScript code using best practices:

// TODO: Refactor this code
function getData(id: any): any {
  var result = db.find(id);
  if (result) {
    return result;
  } else {
    return null;
  }
}

function process(data: any) {
  var x = data.value;
  if (x > 100) {
    return x * 2;
  }
  return x;
}

// Apply:
// 1. Proper types (no any)
// 2. Good naming
// 3. Explicit return types
// 4. Error handling
// 5. Type guards
// 6. Modern syntax (const/let)
// 7. Extract magic numbers
// 8. Add documentation

---

Key Takeaways

1. No any - use unknown or proper types

2. Explicit returns - always specify return types

3. Strict null checks - handle null/undefined explicitly

4. Type guards - narrow unions safely

5. Descriptive names - code is read more than written

6. Error handling - typed custom errors

7. ESLint - catch issues automatically

8. Patterns - builder, factory, repository

9. Code review - checklist catches 90% of bugs

---

What I Learned

PR #183 went to production with any types. $47,000 in failed payments.

That code review led to our TypeScript Best Practices Guide. 90% of issues now caught before merge. Bug rate down 61%.

The standards we implemented:

1. No any - enforced by ESLint

2. Explicit returns - required in code review

3. Type guards - for all union types

4. Naming conventions - automated checks

5. Error handling - custom typed errors only

Before standards, TypeScript was inconsistently applied. Some files had perfect types. Others had any everywhere. Code quality was a lottery.

After standards, every file follows the same patterns. New devs know what's expected. Code review is faster. Bugs are rare.

The lesson: TypeScript without standards is JavaScript with extra syntax. The compiler can only help if you let it.

Enforce best practices. Make them automatic. Watch your bug rate plummet.

---

Next: Building a Real-World CLI Tool

In the next article, we'll build a complete TypeScript CLI tool from scratch. You'll learn how I built a deployment automation tool that saved our team 15 hours per week.