Software Documentation Best Practices — A Complete Beginner's Guide

/**
 * UserAccountService — Reference Documentation Example
 *
 * PURPOSE: Manages the full lifecycle of user accounts in the application.
 * This includes creation, authentication, suspension, and deletion.
 *
 * DESIGN DECISION: We chose to keep authentication logic here (rather than a
 * separate AuthService) because in our current scale, the two responsibilities
 * are tightly coupled. If the app grows beyond 100k users, consider splitting them.
 *
 * DEPENDENCIES: Requires a live DatabaseConnection. See DatabaseConfig.java.
 */
public class UserAccountService {

    private final DatabaseConnection databaseConnection;
    private final PasswordHasher passwordHasher;

    /**
     * Creates a new UserAccountService.
     *
     * @param databaseConnection An active, non-null connection to the user database.
     * @param passwordHasher     The hashing strategy to use (e.g., BCrypt, Argon2).
     *                           Never pass a plain-text or reversible hasher here.
     */
    public UserAccountService(DatabaseConnection databaseConnection, PasswordHasher passwordHasher) {
        this.databaseConnection = databaseConnection;
        this.passwordHasher = passwordHasher;
    }

    /**
     * Registers a new user account.
     *
     * HOW IT WORKS:
     *   1. Validates that the email is unique in the database.
     *   2. Hashes the password before storage (plain text is NEVER stored).
     *   3. Persists the new user record and returns the generated user ID.
     *
     * @param email    The user's email address. Must be unique. Cannot be null.
     * @param password The raw password entered by the user. Min 8 characters.
     * @return         The newly created user's unique ID (a positive long).
     * @throws DuplicateEmailException   If that email already exists in the system.
     * @throws InvalidPasswordException  If the password fails strength requirements.
     *
     * EXAMPLE USAGE:
     *   long newUserId = accountService.registerUser("alice@example.com", "Str0ngP@ss!");
     *   System.out.println("Created user with ID: " + newUserId);
     */
    public long registerUser(String email, String password)
            throws DuplicateEmailException, InvalidPasswordException {

        // Guard: never store an account if the email is already taken
        if (databaseConnection.emailExists(email)) {
            throw new DuplicateEmailException("Account already exists for: " + email);
        }

        // Guard: enforce password policy before doing any DB work
        if (password == null || password.length() < 8) {
            throw new InvalidPasswordException("Password must be at least 8 characters.");
        }

        // Hash the password — we store the hash, NEVER the original string
        String hashedPassword = passwordHasher.hash(password);

        // Persist the new user and return their auto-generated database ID
        return databaseConnection.insertNewUser(email, hashedPassword);
    }
}

public class PaymentProcessor {

    // BAD COMMENT STYLE — What not to do
    // ─────────────────────────────────────────────────────────────────

    public double calculateTotalBad(double itemPrice, int quantity, double taxRate) {
        double subtotal = itemPrice * quantity; // multiply itemPrice by quantity
        double taxAmount = subtotal * taxRate;  // multiply subtotal by taxRate
        double total = subtotal + taxAmount;    // add subtotal and taxAmount
        return total;                           // return total
    }
    // Every comment above is useless — the code already says exactly that.


    // GOOD COMMENT STYLE — What to aim for
    // ─────────────────────────────────────────────────────────────────

    public double calculateTotal(double itemPrice, int quantity, double taxRate) {
        double subtotal = itemPrice * quantity;

        // Tax is calculated on the subtotal, NOT on any already-discounted price.
        // This matches our legal obligation in jurisdictions where tax
        // applies before merchant discounts (see compliance doc: TAX-2024-03).
        double taxAmount = subtotal * taxRate;

        return subtotal + taxAmount;
    }

    public double applyEarlyBirdDiscount(double originalPrice, long purchaseTimestampMs) {
        long currentTimeMs = System.currentTimeMillis();
        long nineAm = getTodayNineAmTimestampMs();
        long elevenAm = getTodayElevenAmTimestampMs();

        // Only apply the discount during the 9-11am window.
        // WHY this check exists: marketing ran a campaign where the first
        // 2 hours of each day have a 10% discount. The check uses strict
        // less-than on elevenAm so a purchase at exactly 11:00:00.000 does
        // NOT qualify — product team confirmed this edge case on 2024-08-12.
        if (purchaseTimestampMs >= nineAm && purchaseTimestampMs < elevenAm) {
            return originalPrice * 0.90; // 10% discount applied
        }

        return originalPrice;
    }

    // TODO(dev-team): Replace this stub with a real calendar utility in v2.1
    // Tracked in GitHub issue #447
    private long getTodayNineAmTimestampMs() { return 0L; }
    private long getTodayElevenAmTimestampMs() { return 0L; }
}

# TaskFlow — Lightweight Task Queue for Java Applications

TaskFlow lets you run background jobs in your Java app without setting up
RabbitMQ, Kafka, or any external broker. Everything runs in-process.
Perfect for small-to-medium apps where you need async work but don't want
infrastructure overhead.

## Who is this for?
Developers building Spring Boot or plain Java apps who need to defer work
(like sending emails or resizing images) to a background thread.

---

## Quick Start (< 5 minutes)

### 1. Add the dependency
```xml
<dependency>
  <groupId>io.thecodeforge</groupId>
  <artifactId>taskflow</artifactId>
  <version>1.2.0</version>
</dependency>
```

### 2. Define a job
```java
public class SendWelcomeEmailJob implements TaskFlowJob {
    @Override
    public void execute(String userEmail) {
        EmailClient.send(userEmail, "Welcome aboard!");
    }
}
```

### 3. Enqueue it
```java
TaskQueue queue = new TaskQueue(workerThreadCount: 4);
queue.enqueue(new SendWelcomeEmailJob(), "alice@example.com");
```

That's it. The job runs in the background. Your main thread is free immediately.

---

## Configuration

| Option            | Default | Description                              |
|-------------------|---------|------------------------------------------|
| workerThreadCount | 2       | Number of parallel background workers    |
| maxQueueSize      | 1000    | Jobs accepted before blocking callers    |
| retryOnFailure    | true    | Retry a failed job up to 3 times         |

---

## Running Tests
```bash
./mvnw test
```
All tests should pass in under 10 seconds on a standard laptop.

---

## Known Limitations
- Jobs do NOT survive a JVM restart. For durability, use a persistent broker.
- Not suitable for jobs that take longer than 30 minutes (no heartbeat support yet).
  See issue #88 for progress on this.

---

## Contributing
PRs welcome. Please read CONTRIBUTING.md first — it's short, we promise.

## License
MIT — use it freely, attribution appreciated.

/**
 * TemperatureConverter — Utility class for converting between temperature scales.
 *
 * <p>Supports Celsius, Fahrenheit, and Kelvin. All conversion methods are stateless
 * and thread-safe — safe to call from multiple threads simultaneously.</p>
 *
 * <p>This class intentionally has no constructor — use the static methods directly:
 * <pre>
 *   double boilingInF = TemperatureConverter.celsiusToFahrenheit(100.0);
 * </pre>
 * </p>
 *
 * @author  TheCodeForge Team
 * @version 2.0
 * @since   1.0
 */
public class TemperatureConverter {

    // Private constructor prevents instantiation — this is a pure utility class.
    // All methods are static; there's no state to hold in an instance.
    private TemperatureConverter() {}

    /**
     * Converts a temperature from Celsius to Fahrenheit.
     *
     * <p>Formula used: F = (C × 9/5) + 32</p>
     *
     * @param  celsius The temperature in degrees Celsius.
     *                 Valid range: -273.15 and above (absolute zero is the floor).
     * @return         The equivalent temperature in degrees Fahrenheit.
     * @throws IllegalArgumentException if {@code celsius} is below absolute zero (-273.15°C).
     *
     * @see #fahrenheitToCelsius(double)
     */
    public static double celsiusToFahrenheit(double celsius) {
        if (celsius < -273.15) {
            throw new IllegalArgumentException(
                "Temperature " + celsius + "°C is below absolute zero. That's physically impossible."
            );
        }
        // The classic formula: multiply by 9/5 then add 32
        return (celsius * 9.0 / 5.0) + 32.0;
    }

    /**
     * Converts a temperature from Fahrenheit to Celsius.
     *
     * <p>Formula used: C = (F − 32) × 5/9</p>
     *
     * @param  fahrenheit The temperature in degrees Fahrenheit.
     *                    Valid range: -459.67 and above (absolute zero in Fahrenheit).
     * @return            The equivalent temperature in degrees Celsius.
     * @throws IllegalArgumentException if {@code fahrenheit} is below absolute zero (-459.67°F).
     */
    public static double fahrenheitToCelsius(double fahrenheit) {
        if (fahrenheit < -459.67) {
            throw new IllegalArgumentException(
                "Temperature " + fahrenheit + "°F is below absolute zero."
            );
        }
        return (fahrenheit - 32.0) * 5.0 / 9.0;
    }

    /**
     * Converts a temperature from Celsius to Kelvin.
     *
     * <p>Kelvin is the SI base unit for temperature. Zero Kelvin = absolute zero.
     * There are no negative Kelvin values.</p>
     *
     * @param  celsius The temperature in degrees Celsius (must be >= -273.15).
     * @return         The equivalent temperature in Kelvin (always >= 0).
     * @throws IllegalArgumentException if {@code celsius} is below -273.15.
     */
    public static double celsiusToKelvin(double celsius) {
        if (celsius < -273.15) {
            throw new IllegalArgumentException(
                "Cannot convert " + celsius + "°C to Kelvin: value is below absolute zero."
            );
        }
        // Kelvin = Celsius + 273.15 (by definition of the Kelvin scale)
        return celsius + 273.15;
    }

    // Quick demo — run this class directly to see conversions in action
    public static void main(String[] args) {
        double boilingPointCelsius = 100.0;
        double bodyTempFahrenheit  = 98.6;
        double absoluteZeroCelsius = -273.15;

        System.out.println("=== Temperature Converter Demo ===");

        System.out.printf("%.1f°C in Fahrenheit = %.1f°F%n",
            boilingPointCelsius,
            celsiusToFahrenheit(boilingPointCelsius));

        System.out.printf("%.1f°F in Celsius = %.2f°C%n",
            bodyTempFahrenheit,
            fahrenheitToCelsius(bodyTempFahrenheit));

        System.out.printf("%.2f°C in Kelvin = %.2fK%n",
            absoluteZeroCelsius,
            celsiusToKelvin(absoluteZeroCelsius));

        System.out.println("\nAttempting to convert below absolute zero...");
        try {
            celsiusToFahrenheit(-300.0); // This will throw
        } catch (IllegalArgumentException exception) {
            System.out.println("Caught expected error: " + exception.getMessage());
        }
    }
}