Clean Code Principles Explained — Writing Code That Humans Can Actually Read

public class SubscriptionRenewalService {

    // BAD: what is 'd'? What is 'uts'? What does 86400 mean?
    // public boolean chk(int d, long uts) {
    //     return (System.currentTimeMillis() / 1000) - uts > d * 86400;
    // }

    // GOOD: the intent is crystal clear before you read a single line of logic
    private static final int SECONDS_PER_DAY = 86_400; // underscore improves readability of large numbers

    /**
     * Returns true if the subscription has been inactive longer than the allowed grace period.
     * Used to determine whether to send a renewal reminder or suspend the account.
     */
    public boolean hasGracePeriodExpired(int gracePeriodInDays, long lastActiveTimestampSeconds) {
        long currentTimeSeconds = System.currentTimeMillis() / 1_000;
        long secondsInactive = currentTimeSeconds - lastActiveTimestampSeconds;
        long gracePeriodInSeconds = (long) gracePeriodInDays * SECONDS_PER_DAY;

        // We compare seconds directly to avoid floating-point errors from day conversion
        return secondsInactive > gracePeriodInSeconds;
    }

    public static void main(String[] args) {
        SubscriptionRenewalService service = new SubscriptionRenewalService();

        // Simulate a user who last logged in 8 days ago
        long eightDaysAgoInSeconds = (System.currentTimeMillis() / 1_000) - (8L * 86_400);

        boolean expired = service.hasGracePeriodExpired(7, eightDaysAgoInSeconds);
        System.out.println("Grace period expired: " + expired); // Should print true

        boolean stillActive = service.hasGracePeriodExpired(30, eightDaysAgoInSeconds);
        System.out.println("Grace period expired (30-day plan): " + stillActive); // Should print false
    }
}

import java.util.regex.Pattern;

public class UserRegistrationService {

    private static final Pattern EMAIL_PATTERN =
        Pattern.compile("^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$");

    private static final int MINIMUM_PASSWORD_LENGTH = 8;

    // BAD: this function does validation, transformation, AND persistence — three jobs
    // public void registerUser(String email, String password, String rawName) {
    //     if (!email.contains("@")) throw new IllegalArgumentException("bad email");
    //     if (password.length() < 8) throw new IllegalArgumentException("short password");
    //     String name = rawName.trim();
    //     // ... then 40 more lines of saving to DB and sending email
    // }

    // GOOD: each method has exactly one job and a name that proves it

    /** Orchestrates the full registration flow. Reads like a checklist. */
    public void registerNewUser(String email, String rawPassword, String rawDisplayName) {
        validateEmailFormat(email);
        validatePasswordStrength(rawPassword);
        String sanitizedDisplayName = sanitizeDisplayName(rawDisplayName);
        UserRecord newUser = buildUserRecord(email, rawPassword, sanitizedDisplayName);
        saveUserToDatabase(newUser);
        sendWelcomeEmail(newUser);
    }

    /** Validates format only — does NOT check if email already exists (separate concern) */
    private void validateEmailFormat(String email) {
        if (email == null || !EMAIL_PATTERN.matcher(email).matches()) {
            throw new IllegalArgumentException(
                "Invalid email format: '" + email + "'");
        }
    }

    /** Enforces minimum security rules for passwords */
    private void validatePasswordStrength(String password) {
        if (password == null || password.length() < MINIMUM_PASSWORD_LENGTH) {
            throw new IllegalArgumentException(
                "Password must be at least " + MINIMUM_PASSWORD_LENGTH + " characters.");
        }
    }

    /** Removes dangerous whitespace — does NOT validate content */
    private String sanitizeDisplayName(String rawDisplayName) {
        return rawDisplayName == null ? "" : rawDisplayName.trim();
    }

    private UserRecord buildUserRecord(String email, String password, String displayName) {
        // In production: hash the password here — never store plaintext
        return new UserRecord(email, password, displayName);
    }

    private void saveUserToDatabase(UserRecord user) {
        // Simulated — would call your repository layer in a real system
        System.out.println("[DB] Saving user: " + user.email());
    }

    private void sendWelcomeEmail(UserRecord user) {
        // Simulated — would call your email service in a real system
        System.out.println("[Email] Welcome email sent to: " + user.email());
    }

    // Simple record to group related user data instead of passing 4 loose parameters
    record UserRecord(String email, String password, String displayName) {}

    public static void main(String[] args) {
        UserRegistrationService service = new UserRegistrationService();

        try {
            service.registerNewUser("alice@example.com", "securePass99", "  Alice  ");
        } catch (IllegalArgumentException e) {
            System.out.println("Registration failed: " + e.getMessage());
        }

        System.out.println("---");

        try {
            // This should fail validation
            service.registerNewUser("not-an-email", "short", "Bob");
        } catch (IllegalArgumentException e) {
            System.out.println("Registration failed: " + e.getMessage());
        }
    }
}

public class PaymentProcessor {

    // BAD COMMENTS — these add noise, not signal
    //
    // // increment i by 1
    // i++;
    //
    // // check if amount is greater than zero
    // if (amount > 0) { ... }
    //
    // // This is the payment method
    // public void pay() { ... }

    private static final double STRIPE_MINIMUM_CHARGE_DOLLARS = 0.50;

    // GOOD COMMENT — explains WHY, not WHAT. The code is clear; the business rule is not.
    /**
     * Stripe rejects any charge below $0.50 regardless of currency.
     * We validate here rather than letting the API call fail to avoid
     * unnecessary network round-trips and confusing Stripe error codes.
     * See: https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts
     */
    public void chargeCustomer(String customerId, double amountInDollars) {
        if (amountInDollars < STRIPE_MINIMUM_CHARGE_DOLLARS) {
            throw new IllegalArgumentException(
                "Charge amount $" + amountInDollars +
                " is below the Stripe minimum of $" + STRIPE_MINIMUM_CHARGE_DOLLARS);
        }

        // GOOD COMMENT — flags a non-obvious gotcha future developers will thank you for
        // We deliberately do NOT round amountInDollars here.
        // Stripe accepts fractional cents and rounds on their side.
        // Rounding here caused a $0.01 discrepancy in reconciliation reports (see issue #4821).
        submitChargeToStripe(customerId, amountInDollars);
    }

    private void submitChargeToStripe(String customerId, double amount) {
        // Simulated payment gateway call
        System.out.printf("[Stripe] Charging customer '%s' — $%.2f%n", customerId, amount);
    }

    public static void main(String[] args) {
        PaymentProcessor processor = new PaymentProcessor();

        // Valid charge
        processor.chargeCustomer("cus_abc123", 29.99);

        // Below Stripe minimum
        try {
            processor.chargeCustomer("cus_abc123", 0.25);
        } catch (IllegalArgumentException e) {
            System.out.println("Charge rejected: " + e.getMessage());
        }
    }
}

import java.util.List;

public class InvoiceFormatter {

    // Vertical grouping: constants together, logically separated from the constructor
    private static final String CURRENCY_SYMBOL = "$";
    private static final String LINE_SEPARATOR = "-".repeat(40);

    private final String businessName;
    private final String customerName;

    public InvoiceFormatter(String businessName, String customerName) {
        this.businessName = businessName;
        this.customerName = customerName;
    }

    // High-level orchestration at the TOP — you see the big picture first
    public String formatInvoice(List<LineItem> lineItems) {
        StringBuilder invoice = new StringBuilder();

        appendHeader(invoice);
        appendLineItems(invoice, lineItems);
        appendTotal(invoice, calculateTotal(lineItems));

        return invoice.toString();
    }

    // Lower-level detail follows BELOW the caller — the newspaper structure
    private void appendHeader(StringBuilder invoice) {
        invoice.append(LINE_SEPARATOR).append("\n");
        invoice.append("Invoice from: ").append(businessName).append("\n");
        invoice.append("Bill to:      ").append(customerName).append("\n");
        invoice.append(LINE_SEPARATOR).append("\n");
    }

    private void appendLineItems(StringBuilder invoice, List<LineItem> lineItems) {
        for (LineItem item : lineItems) {
            // Left-align description, right-align amount — clear visual hierarchy
            invoice.append(String.format("%-25s %s%.2f%n",
                item.description(), CURRENCY_SYMBOL, item.unitPrice()));
        }
        invoice.append(LINE_SEPARATOR).append("\n");
    }

    private void appendTotal(StringBuilder invoice, double total) {
        invoice.append(String.format("%-25s %s%.2f%n", "TOTAL", CURRENCY_SYMBOL, total));
        invoice.append(LINE_SEPARATOR).append("\n");
    }

    private double calculateTotal(List<LineItem> lineItems) {
        return lineItems.stream()
            .mapToDouble(LineItem::unitPrice)
            .sum();
    }

    // Related data grouped into a record — no loose parallel arrays or parameter lists
    record LineItem(String description, double unitPrice) {}

    public static void main(String[] args) {
        InvoiceFormatter formatter = new InvoiceFormatter("TheCodeForge Ltd", "Alice Nguyen");

        List<LineItem> items = List.of(
            new LineItem("Annual Pro Subscription", 99.00),
            new LineItem("Priority Support Add-on", 29.99),
            new LineItem("Setup Fee", 0.00)
        );

        System.out.println(formatter.formatInvoice(items));
    }
}