Part 1: Foundations and Principles

Series Navigation: ← Back to Series Overview | Part 2: Code Review Process and Best Practices →

Introduction

When I started building TypeScript microservices, I quickly learned that writing code that "just works" isn't enough. Over the years, I've worked on services handling millions of requests daily, and I've seen firsthand how code quality directly impacts maintainability, reliability, and team velocity. Code review and refactoring aren't just checkboxes in a development process—they're essential disciplines that separate fragile systems from resilient ones.

In my current microservices architecture, we have services written in TypeScript running on Node.js, handling everything from user authentication to payment processing. Each service has its own repository, CI/CD pipeline, and deployment cycle. Without rigorous code review and continuous refactoring, technical debt would accumulate faster than we could ship features.

This series draws from my practical experience building and maintaining production TypeScript microservices. I'll share real patterns, real challenges, and real solutions—no hypothetical scenarios.

Why Code Review and Refactoring Matter

The Real Cost of Poor Code Quality

In one of my earlier projects, we had a payment processing service that grew organically over two years. Functions were hundreds of lines long, dependencies were tightly coupled, and testing was an afterthought. When we needed to add a new payment provider, what should have been a week's work turned into a month-long refactoring effort. The code worked, but it was unmaintainable.

From this experience, I learned:

1. Technical debt compounds: Small shortcuts accumulate into major roadblocks

2. Refactoring gets harder over time: The longer you wait, the riskier it becomes

3. Poor code slows feature development: New developers struggle to understand complex code

4. Bugs hide in complexity: The more convoluted the code, the more subtle the bugs

Code Review as Quality Gate

Code review serves multiple purposes beyond catching bugs:

• Knowledge sharing: Team members learn from each other's approaches

• Consistency: Maintains architectural patterns across the codebase

• Mentorship: Senior developers guide junior developers

• Collective ownership: Everyone feels responsible for code quality

In my team, we've established that no code reaches production without review. This isn't bureaucracy—it's saved us from production incidents countless times.

Core Principles of Code Quality

Through maintaining TypeScript microservices, I've distilled code quality into several core principles:

1. Readability Over Cleverness

// ❌ Clever but hard to understand
const p = (u: any) => u.r === 'a' && u.s && Date.now() - u.l < 3600000;

// ✅ Clear and maintainable
interface User {
  role: string;
  isActive: boolean;
  lastLoginTimestamp: number;
}

function isActiveAdmin(user: User): boolean {
  const isAdmin = user.role === 'admin';
  const isActive = user.isActive;
  const ONE_HOUR_MS = 3600000;
  const recentlyLoggedIn = Date.now() - user.lastLoginTimestamp < ONE_HOUR_MS;
  
  return isAdmin && isActive && recentlyLoggedIn;
}

Key Takeaways:

• Descriptive names communicate intent

• Types provide documentation

• Logic is self-explanatory

• Future developers (including yourself) will thank you

2. Single Responsibility Principle

In my user service, I had a function handling authentication, logging, and session management. Refactoring it into separate responsibilities made testing and maintenance significantly easier.

// ❌ Multiple responsibilities
async function authenticateUser(email: string, password: string) {
  console.log(`Login attempt for ${email}`);
  const user = await db.users.findByEmail(email);
  
  if (!user) {
    console.error('User not found');
    return null;
  }
  
  const isValid = await bcrypt.compare(password, user.passwordHash);
  
  if (!isValid) {
    console.error('Invalid password');
    return null;
  }
  
  const sessionId = crypto.randomUUID();
  await db.sessions.create({
    userId: user.id,
    sessionId,
    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000)
  });
  
  console.log(`User ${email} logged in successfully`);
  return { user, sessionId };
}

// ✅ Separated responsibilities
class AuthenticationService {
  constructor(
    private userRepository: UserRepository,
    private passwordService: PasswordService,
    private sessionService: SessionService,
    private logger: Logger
  ) {}

  async authenticate(email: string, password: string): Promise<AuthResult> {
    this.logger.info('Authentication attempt', { email });
    
    const user = await this.userRepository.findByEmail(email);
    if (!user) {
      this.logger.warn('User not found', { email });
      throw new UserNotFoundError(email);
    }
    
    const isValidPassword = await this.passwordService.verify(
      password, 
      user.passwordHash
    );
    
    if (!isValidPassword) {
      this.logger.warn('Invalid password attempt', { email });
      throw new InvalidPasswordError();
    }
    
    const session = await this.sessionService.createSession(user.id);
    
    this.logger.info('Authentication successful', { 
      userId: user.id,
      sessionId: session.id 
    });
    
    return { user, session };
  }
}

Benefits:

• Each class has one reason to change

• Easy to test in isolation

• Dependencies are explicit and injectable

• Logging is handled consistently

3. Fail Fast and Explicit

// ❌ Silent failures and unclear errors
async function processPayment(orderId: string, amount: number) {
  try {
    const order = await getOrder(orderId);
    if (order) {
      const result = await chargeCard(order.customerId, amount);
      if (result) {
        return result;
      }
    }
  } catch (e) {
    return null;
  }
  return null;
}

// ✅ Explicit validation and error handling
async function processPayment(
  orderId: string, 
  amount: number
): Promise<PaymentResult> {
  // Validate inputs
  if (!orderId || orderId.trim() === '') {
    throw new InvalidOrderIdError('Order ID cannot be empty');
  }
  
  if (amount <= 0) {
    throw new InvalidAmountError('Amount must be positive');
  }
  
  // Fetch order with explicit error handling
  const order = await this.orderRepository.findById(orderId);
  if (!order) {
    throw new OrderNotFoundError(orderId);
  }
  
  // Verify order state
  if (order.status !== OrderStatus.Pending) {
    throw new InvalidOrderStateError(
      `Cannot process payment for order in ${order.status} state`
    );
  }
  
  // Process payment
  try {
    const paymentResult = await this.paymentGateway.charge(
      order.customerId,
      amount,
      { orderId }
    );
    
    return paymentResult;
  } catch (error) {
    if (error instanceof PaymentGatewayError) {
      throw new PaymentProcessingError(
        `Payment gateway error: ${error.message}`,
        error
      );
    }
    throw error;
  }
}

Key Points:

• Input validation happens early

• Errors are specific and actionable

• No silent failures

• Error handling is explicit, not buried in try-catch

4. Dependencies Should Be Explicit

// ❌ Hidden dependencies
class UserService {
  async createUser(email: string, password: string) {
    // Hidden dependency on global database connection
    const user = await db.users.create({ email, password });
    
    // Hidden dependency on environment variable
    await sendEmail(email, process.env.WELCOME_TEMPLATE_ID);
    
    return user;
  }
}

// ✅ Explicit dependencies via constructor injection
interface IUserRepository {
  create(data: CreateUserData): Promise<User>;
}

interface IEmailService {
  sendWelcomeEmail(email: string): Promise<void>;
}

class UserService {
  constructor(
    private userRepository: IUserRepository,
    private emailService: IEmailService,
    private config: AppConfig
  ) {}

  async createUser(email: string, password: string): Promise<User> {
    const user = await this.userRepository.create({ email, password });
    await this.emailService.sendWelcomeEmail(email);
    return user;
  }
}

Advantages:

• Dependencies are clear from the constructor

• Easy to mock for testing

• Configuration is centralized

• No global state

The Refactoring Mindset

Refactoring isn't about rewriting code because you don't like it. It's about systematic improvement with these guidelines:

When to Refactor

Based on my experience, these are good triggers:

1. Before adding a feature: Make the code ready to accept the change

2. When you touch code for a bug fix: Leave it better than you found it

3. During code review: If code is hard to review, it needs refactoring

4. When patterns emerge: Extract common code into reusable utilities

When NOT to Refactor

1. During a production incident: Fix the bug, refactor later

2. When you don't have tests: Add tests first

3. Without understanding the code: Study before changing

4. Just because it's "ugly": There must be a tangible benefit

The Boy Scout Rule

"Always leave the code better than you found it."

In my team, we apply this religiously. Even if you're just fixing a typo, if you notice a variable name could be clearer or a function could be extracted, do it. Small improvements compound over time.

Setting Up for Success

Code Review Culture

In my organization, we've built a code review culture based on:

1. Respect: Critique code, not people

2. Learning: Reviews are teaching opportunities

3. Timeliness: Reviews shouldn't block progress for days

4. Thoroughness: But also shouldn't be rubber stamps

Measuring Code Quality

We track several metrics:

• Code coverage: Target 80%+ for critical services

• Cyclomatic complexity: Flag functions above 10

• PR size: Encourage small, focused changes

• Review time: Track how long reviews take

Tools We Use

For our TypeScript microservices:

• ESLint: Enforce coding standards

• Prettier: Consistent formatting

• TypeScript strict mode: Catch type errors early

• SonarQube: Track technical debt

• Husky: Pre-commit hooks

Real-World Example: Refactoring a Service Method

Here's a method from my actual notification service that needed refactoring:

Before Refactoring:

async function notify(userId: string, type: string, data: any) {
  const user = await db.query('SELECT * FROM users WHERE id = ?', [userId]);
  if (!user) return;
  
  let message;
  if (type === 'order') {
    message = `Your order ${data.orderId} is ${data.status}`;
  } else if (type === 'payment') {
    message = `Payment of $${data.amount} ${data.result}`;
  } else {
    message = data.message;
  }
  
  if (user.email_notifications) {
    await sendEmail(user.email, message);
  }
  
  if (user.sms_notifications) {
    await sendSMS(user.phone, message);
  }
  
  await db.query('INSERT INTO notifications (user_id, message, type) VALUES (?, ?, ?)', 
    [userId, message, type]);
}

Issues Identified:

• Direct database queries (no repository pattern)

• Type isn't type-safe (using string instead of enum)

• Message composition logic mixed with notification logic

• No error handling

• Hard to test

After Refactoring:

enum NotificationType {
  Order = 'order',
  Payment = 'payment',
  General = 'general'
}

interface NotificationData {
  type: NotificationType;
  payload: OrderPayload | PaymentPayload | GeneralPayload;
}

class NotificationService {
  constructor(
    private userRepository: UserRepository,
    private emailService: EmailService,
    private smsService: SmsService,
    private notificationRepository: NotificationRepository,
    private messageComposer: MessageComposer,
    private logger: Logger
  ) {}

  async sendNotification(
    userId: string, 
    notificationData: NotificationData
  ): Promise<void> {
    // Fetch user preferences
    const user = await this.userRepository.findById(userId);
    if (!user) {
      throw new UserNotFoundError(userId);
    }

    // Compose message based on type
    const message = this.messageComposer.compose(notificationData);

    // Send via enabled channels
    const promises: Promise<void>[] = [];
    
    if (user.preferences.emailEnabled) {
      promises.push(
        this.sendEmailNotification(user.email, message)
      );
    }
    
    if (user.preferences.smsEnabled && user.phone) {
      promises.push(
        this.sendSmsNotification(user.phone, message)
      );
    }

    // Execute sends in parallel
    await Promise.all(promises);

    // Record notification
    await this.notificationRepository.create({
      userId,
      message,
      type: notificationData.type,
      sentAt: new Date()
    });

    this.logger.info('Notification sent', { 
      userId, 
      type: notificationData.type 
    });
  }

  private async sendEmailNotification(
    email: string, 
    message: string
  ): Promise<void> {
    try {
      await this.emailService.send(email, message);
    } catch (error) {
      this.logger.error('Email notification failed', { email, error });
      // Don't throw - we don't want one channel failure to block others
    }
  }

  private async sendSmsNotification(
    phone: string, 
    message: string
  ): Promise<void> {
    try {
      await this.smsService.send(phone, message);
    } catch (error) {
      this.logger.error('SMS notification failed', { phone, error });
    }
  }
}

Improvements:

• Type-safe with enums and interfaces

• Dependencies injected and explicit

• Single Responsibility Principle followed

• Error handling per channel

• Parallel execution for performance

• Easy to test each component

• Logging for observability

Conclusion

Code review and refactoring are skills that develop over time. In this part, we covered the foundational principles:

• Readability over cleverness

• Single Responsibility for maintainability

• Fail fast with explicit errors

• Explicit dependencies for testability

• Continuous improvement mindset

In Part 2, we'll dive deep into the code review process—how to give effective feedback, what to look for during reviews, and how to build a productive review culture in your team.

Next Steps:

1. Review your current codebase with these principles in mind

2. Identify one function that violates Single Responsibility

3. Practice refactoring it with proper tests in place

Series Navigation: ← Back to Series Overview | Part 2: Code Review Process and Best Practices →