Clean Code Principles: Writing Maintainable, Testable, and Scalable Software

// ❌ Bad: Unclear names
function calc(a, b) {
  return a * b * 0.2;
}
const d = new Date();
const t = 86400000;

// ✅ Good: Intention-revealing names
function calculateOrderDiscount(orderTotal, itemCount) {
  const DISCOUNT_RATE = 0.2;
  return orderTotal * itemCount * DISCOUNT_RATE;
}
const currentDate = new Date();
const MILLISECONDS_PER_DAY = 86400000;

// Naming conventions:
// - Use pronounceable names (getUserProfile vs getUsrPrfl)
// - Use searchable names (MAX_RETRIES vs 3)
// - Avoid mental mapping (i, j, k only in short loops)
// - Class names: nouns (User, Order, PaymentProcessor)
// - Function names: verbs (getUser, processPayment, validateEmail)
// - Boolean names: is/has/can (isActive, hasPermission, canDelete)

// ❌ Bad: Inconsistent naming
function getUser() {}
function retrieveProfile() {}
function fetchAccount() {}

// ✅ Good: Consistent naming
function getUser() {}
function getProfile() {}
function getAccount() {}

// ❌ Bad: Function does too many things
function processUserOrder(userId, items) {
  // Validate user
  const user = database.query('SELECT * FROM users WHERE id = ?', userId);
  if (!user) throw new Error('User not found');
  if (!user.isActive) throw new Error('User inactive');
  
  // Calculate total
  let total = 0;
  for (const item of items) {
    const product = getProduct(item.id);
    total += product.price * item.quantity;
  }
  
  // Apply discount
  if (user.isPremium) total *= 0.9;
  
  // Process payment
  const paymentResult = stripe.charge(user.cardId, total);
  if (!paymentResult.success) throw new Error('Payment failed');
  
  // Send email
  sendEmail(user.email, 'Order confirmation', total);
  
  // Update inventory
  for (const item of items) {
    updateStock(item.id, -item.quantity);
  }
  
  return { orderId: generateId(), total };
}

// ✅ Good: Each function does one thing
function processUserOrder(userId, items) {
  const user = validateActiveUser(userId);
  const total = calculateOrderTotal(items, user);
  const payment = processPayment(user, total);
  await sendOrderConfirmation(user.email, total);
  await updateInventory(items);
  
  return createOrder(user.id, items, total, payment.id);
}

function validateActiveUser(userId) {
  const user = getUserById(userId);
  if (!user) throw new UserNotFoundError(userId);
  if (!user.isActive) throw new InactiveUserError(userId);
  return user;
}

function calculateOrderTotal(items, user) {
  const subtotal = items.reduce((sum, item) => {
    const product = getProduct(item.id);
    return sum + (product.price * item.quantity);
  }, 0);
  
  return user.isPremium ? applyPremiumDiscount(subtotal) : subtotal;
}

// Benefits:
// - Each function is easy to test
// - Easy to understand what each function does
// - Easy to reuse (validateActiveUser used elsewhere)
// - Easy to modify (change discount logic in one place)

// S - Single Responsibility Principle
// Each class should have only one reason to change

// ❌ Bad: User class does too much
class User {
  constructor(name, email) {
    this.name = name;
    this.email = email;
  }
  
  saveToDatabase() {
    // Database logic
  }
  
  sendWelcomeEmail() {
    // Email logic
  }
  
  generateReport() {
    // Reporting logic
  }
}

// ✅ Good: Separate concerns
class User {
  constructor(name, email) {
    this.name = name;
    this.email = email;
  }
}

class UserRepository {
  save(user) {
    // Database logic
  }
}

class EmailService {
  sendWelcomeEmail(user) {
    // Email logic
  }
}

class UserReportGenerator {
  generate(user) {
    // Reporting logic
  }
}

// O - Open/Closed Principle
// Open for extension, closed for modification

// ❌ Bad: Must modify class for new shapes
class AreaCalculator {
  calculate(shapes) {
    let area = 0;
    for (const shape of shapes) {
      if (shape.type === 'circle') {
        area += Math.PI * shape.radius ** 2;
      } else if (shape.type === 'rectangle') {
        area += shape.width * shape.height;
      }
      // Adding triangle requires modifying this class
    }
    return area;
  }
}

// ✅ Good: Extend without modifying
class Shape {
  area() {
    throw new Error('Must implement area()');
  }
}

class Circle extends Shape {
  constructor(radius) {
    super();
    this.radius = radius;
  }
  
  area() {
    return Math.PI * this.radius ** 2;
  }
}

class Rectangle extends Shape {
  constructor(width, height) {
    super();
    this.width = width;
    this.height = height;
  }
  
  area() {
    return this.width * this.height;
  }
}

class AreaCalculator {
  calculate(shapes) {
    return shapes.reduce((sum, shape) => sum + shape.area(), 0);
  }
}

// D - Dependency Inversion Principle
// Depend on abstractions, not concretions

// ❌ Bad: High-level depends on low-level
class MySQLDatabase {
  save(data) { /* MySQL specific */ }
}

class UserService {
  constructor() {
    this.db = new MySQLDatabase();  // Tightly coupled
  }
  
  saveUser(user) {
    this.db.save(user);
  }
}

// ✅ Good: Depend on interface
class UserService {
  constructor(database) {
    this.database = database;  // Inject dependency
  }
  
  saveUser(user) {
    this.database.save(user);
  }
}

// Can now use any database
const service1 = new UserService(new MySQLDatabase());
const service2 = new UserService(new PostgreSQLDatabase());
const service3 = new UserService(new MockDatabase());  // For testing!

// ❌ Bad: Silent failures
function getUser(id) {
  try {
    return database.query('SELECT * FROM users WHERE id = ?', id);
  } catch (error) {
    console.log(error);
    return null;  // Caller doesn't know it failed
  }
}

// ✅ Good: Explicit error handling
class UserNotFoundError extends Error {
  constructor(userId) {
    super(`User with ID ${userId} not found`);
    this.name = 'UserNotFoundError';
    this.userId = userId;
  }
}

function getUser(id) {
  try {
    const user = database.query('SELECT * FROM users WHERE id = ?', id);
    if (!user) {
      throw new UserNotFoundError(id);
    }
    return user;
  } catch (error) {
    if (error instanceof UserNotFoundError) {
      throw error;  // Re-throw expected errors
    }
    // Log unexpected errors
    logger.error('Database error in getUser', { id, error });
    throw new DatabaseError('Failed to fetch user');
  }
}

// Caller can handle specific errors
try {
  const user = getUser(123);
} catch (error) {
  if (error instanceof UserNotFoundError) {
    return res.status(404).json({ error: 'User not found' });
  }
  return res.status(500).json({ error: 'Internal server error' });
}

// ❌ Bad: Stating the obvious
let i = 0;  // Set i to 0
i++;  // Increment i

// ❌ Bad: Commented-out code (use version control!)
function processData(data) {
  // const result = oldMethod(data);
  // if (result > 10) {
  //   doSomething();
  // }
  return newMethod(data);
}

// ✅ Good: Explain WHY, not WHAT
// Wait 100ms to avoid rate limiting (API allows 10 req/sec)
await sleep(100);

// Handle edge case: negative IDs are from legacy system
if (userId < 0) {
  userId = convertLegacyId(userId);
}

// TODO: Replace with bulk API when available (Q2 2025)
for (const item of items) {
  await saveItem(item);
}

// ✅ Good: Document complex algorithms
/**
 * Implements Levenshtein distance algorithm to calculate
 * similarity between two strings.
 * 
 * Time complexity: O(m * n)
 * Space complexity: O(m * n)
 * 
 * @param {string} str1 - First string
 * @param {string} str2 - Second string
 * @returns {number} Edit distance between strings
 */
function calculateEditDistance(str1, str2) {
  // Implementation...
}

// Best comment is clear code that needs no comment
// ❌ Bad:
const d = 86400000;  // milliseconds in a day

// ✅ Good:
const MILLISECONDS_PER_DAY = 86400000;