Coding Best Practices for Developers

SOLID

SOLID is a set of five principles that promote maintainable and extensible design.

class UserService {
  authenticate() {}
  sendWelcomeEmail() {}
  logLogin() {}
}

class AuthService {
  authenticate() {}
}

class EmailService {
  sendWelcome() {}
}

if (type === "A") { ... }
else if (type === "B") { ... }

interface Handler {
  handle(): void;
}

handlers[type].handle();

class ReadOnlyFile extends File {
  write() {
    throw new Error("Not supported");
  }
}

If it cannot behave like a File, it should not extend it.

interface Machine {
  print();
  scan();
  fax();
}

interface Printer {
  print();
}

interface Scanner {
  scan();
}

class PaymentService {
  constructor(private db: MySQLClient) {}
}

interface PaymentRepository {
  save(payment: Payment): void;
}

class PaymentService {
  constructor(private repo: PaymentRepository) {}
}

DRY (Don't Repeat Yourself)

DRY (Don't Repeat Yourself) is about maintaining a single source of truth, not eliminating every instance of duplication. Duplication becomes a problem when the same business rule is implemented in multiple places, requiring repeated updates and creating opportunities for behavior to diverge. However, introducing abstractions too early can add unnecessary complexity. It's often better to tolerate some duplication until it clearly represents a shared concept rather than a temporary coincidence. The goal is to centralize knowledge, not merely reduce lines of code.

DRY Example

public double calculateOrderTotal(double amount) {
    return amount + (amount * 0.18);
}

public double calculateInvoiceTotal(double amount) {
    return amount + (amount * 0.18);
}

public class TaxCalculator {
    private static final double TAX_RATE = 0.18;

    public static double applyTax(double amount) {
        return amount + (amount * TAX_RATE);
    }
}

public double calculateOrderTotal(double amount) {
    return TaxCalculator.applyTax(amount);
}

public double calculateInvoiceTotal(double amount) {
    return TaxCalculator.applyTax(amount);
}

Why this is DRY: The tax calculation logic exists in one place. When the business rule changes, only the TaxCalculator needs to be updated, reducing maintenance effort and preventing inconsistencies.

KISS (Keep It Simple)

KISS (Keep It Simple, Stupid) emphasizes solving problems with the simplest solution that meets current requirements. Unnecessary complexity often arises from over-abstraction, over-engineering, or designing for hypothetical future needs. Simple code is easier to understand, test, debug, and maintain, making it more resilient to change over time. The goal is not to oversimplify, but to avoid complexity that provides no immediate value.

KISS Example

interface Calculator {
    double calculate(double amount);
}

class TaxStrategy implements Calculator {
    public double calculate(double amount) {
        return amount * 0.18;
    }
}

class TaxContext {
    private Calculator calculator;

    public TaxContext(Calculator calculator) {
        this.calculator = calculator;
    }

    public double execute(double amount) {
        return calculator.calculate(amount);
    }
}

public double applyTax(double amount) {
    return amount + (amount * 0.18);
}

Below are the core principles of effective code structure, each explained with concrete examples.

/controllers
/services
/repositories
/models

/payments
  ├── payment.ts
  ├── refund.ts
  ├── payment_service.ts

// order_service.ts
order.status = "REFUNDED";

// payment_service.ts
order.status = "REFUNDED";

class Order {
  refund() {
    this.status = "REFUNDED";
  }
}

function calculateTax() {}
export function refund() {}
function formatCurrency() {}
export function createInvoice() {}

export function createInvoice() {}
export function refund() {}

// internal helpers
function calculateTax() {}
function formatCurrency() {}

class UserService {
  authenticate() {}
  sendEmail() {}
  generateReport() {}
  exportCSV() {}
}

class AuthService {
  authenticate() {}
}

class ReportService {
  generate() {}
  exportCSV() {}
}

class PaymentService {
  constructor(private db: MySQLClient) {}
}

interface PaymentRepository {
  save(payment: Payment): void;
}

class PaymentService {
  constructor(private repo: PaymentRepository) {}
}

function chargeUser() {
  gateway.charge(globalUser.card);
}

function chargeUser(user: User, gateway: Gateway) {
  gateway.charge(user.card);
}

/utils
  ├── date.ts
  ├── string.ts
  ├── payment.ts

/payments
  ├── payment_formatter.ts

/orders
  ├── order_dates.ts

if (user) {
  if (user.active) {
    if (!user.banned) {
      process(user);
    }
  }
}

if (!user || !user.active || user.banned) {
  return;
}

process(user);

// requires mocking db, cache, logger, email service
test("refund", () => {
  ...
});

test("refund updates order status", () => {
  const order = new Order();

  order.refund();

  expect(order.status).toBe("REFUNDED");
});

if (type === "A") {
  ...
} else if (type === "B") {
  ...
}

interface Handler {
  handle(): void;
}

handlers[type].handle();

Below is a practical, experience-driven guide to common smells and the refactor strategies that scale.

def process_order(raw_order):
    # 80+ lines of mixed responsibilities
    pass

def process_order(raw_order):
    order = validate_and_parse(raw_order)
    validated = apply_business_rules(order)
    persisted = save_order(validated)
    notify_stakeholders(persisted)
    return format_response(persisted)

PricingPolicy.calculate_total(cart, customer_context)
EligibilityService.is_eligible(user, campaign)

class PaymentRequest:
    def __init__(self, user, amount, currency, metadata):
        ...

if not is_valid(order): return error(...)
if not has_inventory(order): return error(...)

result = execute_core_logic(order)
return success(result)

orders/pricing.py
users/permissions.py
notifications/channels.py

function getUser(id: string) {
  try {
    return db.findUser(id);
  } catch (e) {
    console.log(e);
    return null;
  }
}

class NotFoundError extends Error {}

function getUser(id: string): User {
  const user = db.findUser(id);

  if (!user) {
    throw new NotFoundError("User not found");
  }

  return user;
}

function getUser(id: string): Result<User> {
  const user = db.findUser(id);

  return user ? ok(user) : err("USER_NOT_FOUND");
}

test("refund", () => {
  // heavy mocking: db, email, cache, logger
});

test("refund updates order status", () => {
  const order = new Order();

  order.refund();

  expect(order.status).toBe("REFUNDED");
});

• Start with behavior-preserving changes rather than rewriting code out of frustration or perceived disorder. The goal is stability first, structure second.
• Prioritize refactoring areas that are frequently modified or consistently difficult to understand. Cosmetic ugliness alone is not a sufficient reason to restructure code.
• Keep each change small enough that a reviewer can quickly understand intent, scope, and risk. Large, sweeping diffs increase uncertainty and slow down validation.
• Introduce at least one safety mechanism during the refactor: tests, type improvements, assertions, or clearer contracts. Refactoring without guardrails is just rework with hope.
• Stop when the code becomes easier to understand and modify. Refactoring is complete when change becomes safer and clearer, not when the design feels maximally elegant.

• Can another engineer understand the main execution flow without tracing every branch?
• Are names expressing intent, or are comments compensating for unclear naming?
• Is business logic duplicated in multiple places that should share a single source of truth?
• Are dependencies explicit, or is behavior coupled to globals, hidden state, or implicit context?
• Would adding a new case require modifying multiple existing branches or conditions?
• Does the structure make testing simpler, or does it force excessive setup and mocking?

• What are the most important coding best practices for junior developers?▼

  Focus on fundamentals that directly improve readability and maintainability:

  • Clear and intention-revealing naming
  • Small, single-responsibility functions and classes
  • Avoiding duplication of business logic
  • Writing code that is easy to test
  • Keeping dependencies explicit rather than hidden

  Strong foundations matter more than advanced patterns early on.

• Should I prioritize clean code or shipping quickly?▼

  This is often framed as a trade-off, but experienced engineers treat it as a false dichotomy.

  Good structure, naming, and separation of concerns actually increase delivery speed over time. They reduce debugging effort, simplify reviews, and lower the cost of change.

  The real goal is sustainable velocity, not short-term speed achieved through technical debt.

• When do design patterns actually help?▼

  Design patterns are useful when they:

  • Solve a recurring structural problem
  • Reduce complexity in evolving systems
  • Improve clarity between collaborating components

  They are not useful when applied prematurely or used to “future-proof” simple logic. A pattern should reduce friction, not introduce ceremony.

• What usually gets missed when engineers move too fast?▼

  Speed often hides structural issues that accumulate over time, such as:

  • Duplicated business rules across modules
  • Hidden dependencies through global state or implicit context
  • Overgrown classes or functions with mixed responsibilities
  • Inconsistent naming that obscures intent
  • Test complexity caused by tight coupling

  The long-term cost is rarely in writing code. It’s in understanding and safely changing it later.