Java Coding Standards

// 1. Package declaration (always first, no blank line before):
package com.example.banking.service;

// 2. Imports (grouped, no wildcard imports in production code):
import java.util.List;
import java.util.Optional;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import com.example.banking.model.Account;
import com.example.banking.repository.AccountRepository;

// 3. Class Javadoc:
/**
 * Handles core banking operations including deposits, withdrawals,
 * and balance inquiries.
 *
 * @since 2.0
 */

// 4. Class declaration:
@Service
public class AccountService {

    // 5. Constants first:
    private static final int MAX_DAILY_TRANSACTIONS = 50;
    private static final double OVERDRAFT_FEE = 25.0;

    // 6. Static fields:
    private static int totalAccounts = 0;

    // 7. Instance fields:
    private final AccountRepository repository;

    // 8. Constructors:
    public AccountService(AccountRepository repository) {
        this.repository = repository;
    }

    // 9. Public methods:
    public Account findById(Long id) { ... }

    // 10. Package/protected methods:
    void processTransaction(Transaction t) { ... }

    // 11. Private methods:
    private void validateAmount(double amount) { ... }
}

// ── Indentation: 4 spaces (NOT tabs) ────────────────────────────
public void process() {
    if (condition) {
        doSomething();
        if (nested) {
            doNested();
        }
    }
}

// ── Line length: 120 characters max (Google style) ───────────────
// Long method signatures — wrap with 8-space continuation indent:
public ResponseEntity<AccountResponse> createAccount(
        @RequestBody AccountRequest request,
        @PathVariable Long customerId) {
    // ...
}

// ── Braces: K&R style (opening brace on same line) ───────────────
// DO:
public void method() {
    if (condition) {
        // ...
    } else {
        // ...
    }
}

// DON'T (Allman style — non-standard in Java):
public void method()
{
    if (condition)
    {
        // ...
    }
}

// ── Always use braces, even for single-line if/for ───────────────
// DON'T:
if (condition) doSomething();

// DO:
if (condition) {
    doSomething();
}

// ── Blank lines for logical separation ───────────────────────────
public class OrderService {
                                    // one blank line after class opening
    private final OrderRepository repo;
                                    // one blank line between fields and constructor
    public OrderService(OrderRepository repo) {
        this.repo = repo;
    }
                                    // one blank line between methods
    public Order findById(Long id) {
        return repo.findById(id).orElseThrow();
    }
}

// ── Single Responsibility: one method, one job ──────────────────

// DON'T — method doing three things:
public void processOrder(Order order) {
    validateOrder(order);           // validation
    chargePayment(order);           // payment
    sendConfirmationEmail(order);   // notification
    updateInventory(order);         // inventory
}

// DO — split by responsibility, orchestrate at a higher level:
public void processOrder(Order order) {
    orderValidator.validate(order);
    paymentService.charge(order);
    notificationService.sendConfirmation(order);
    inventoryService.deduct(order);
}

// ── Method length: aim for under 20 lines ───────────────────────
// If a method exceeds a screen, extract sub-methods.
// Names of extracted methods document what each block does.

// ── Parameter count: max 3-4 params ─────────────────────────────
// DON'T:
void createUser(String name, String email, int age,
                String address, String phone, String role) { }

// DO — use a parameter object:
void createUser(CreateUserRequest request) { }

// ── Return early to avoid deep nesting ───────────────────────────
// DON'T — pyramid of doom:
public String getDiscount(User user) {
    if (user != null) {
        if (user.isPremium()) {
            if (user.getYearsActive() > 5) {
                return "20%";
            }
        }
    }
    return "0%";
}

// DO — guard clauses:
public String getDiscount(User user) {
    if (user == null) return "0%";
    if (!user.isPremium()) return "0%";
    if (user.getYearsActive() <= 5) return "0%";
    return "20%";
}

// ── Never swallow exceptions silently ──────────────────────────
// DON'T:
try {
    processPayment(order);
} catch (Exception e) {
    // do nothing  ← this hides bugs and makes debugging impossible
}

// DO — at minimum, log it:
try {
    processPayment(order);
} catch (PaymentException e) {
    log.error("Payment failed for order {}: {}", order.getId(), e.getMessage(), e);
    throw new OrderProcessingException("Payment failed", e);
}

// ── Catch specific exceptions, not generic Exception ────────────
// DON'T:
catch (Exception e) { }           // catches everything — hides bugs

// DO:
catch (IOException e) { }         // handle I/O failures specifically
catch (SQLException e) { }        // handle DB failures specifically

// ── Always include the original exception as cause ───────────────
// DON'T:
catch (SQLException e) {
    throw new DataAccessException("DB error");  // loses stack trace
}

// DO:
catch (SQLException e) {
    throw new DataAccessException("DB error", e);  // preserves stack trace
}

// ── Use try-with-resources for closeable resources ───────────────
// DON'T:
Connection conn = dataSource.getConnection();
try {
    // use conn
} finally {
    conn.close();  // easy to forget, exception in finally hides original
}

// DO:
try (Connection conn = dataSource.getConnection()) {
    // conn is automatically closed when block exits
}

// ── Prefer immutability ────────────────────────────────────────
// DON'T:
public class Config {
    public String host;   // mutable public field
    public int port;
}

// DO:
public final class Config {
    private final String host;
    private final int port;

    public Config(String host, int port) {
        this.host = host;
        this.port = port;
    }

    public String getHost() { return host; }
    public int getPort() { return port; }
}

// ── Use Optional instead of returning null ───────────────────────
// DON'T:
public User findByEmail(String email) {
    return null;  // caller might forget to null-check → NPE
}

// DO:
public Optional<User> findByEmail(String email) {
    return Optional.ofNullable(userMap.get(email));
}
// Caller is forced to handle the absent case:
userService.findByEmail(email)
    .ifPresent(user -> sendWelcomeEmail(user));

// ── Favor composition over inheritance ──────────────────────────
// DON'T — deep inheritance for code reuse:
class Vehicle { }
class Car extends Vehicle { }
class ElectricCar extends Car { }
class SelfDrivingElectricCar extends ElectricCar { }  // deep and fragile

// DO — compose with interfaces:
class ElectricCar implements Vehicle, Electric, Autonomous { }

// ── Use constants for magic numbers ─────────────────────────────
// DON'T:
if (userAge >= 18 && transactionAmount > 50000) { }

// DO:
private static final int LEGAL_AGE = 18;
private static final double HIGH_VALUE_THRESHOLD = 50_000.0;

if (userAge >= LEGAL_AGE && transactionAmount > HIGH_VALUE_THRESHOLD) { }

<!-- Checkstyle — enforces formatting and naming conventions -->
<!-- Add to pom.xml: -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.3.0</version>
    <configuration>
        <!-- Google's Java style rules: -->
        <configLocation>google_checks.xml</configLocation>
        <failOnViolation>true</failOnViolation>
    </configuration>
</plugin>

<!-- SpotBugs — finds bug patterns: null dereferences, resource leaks -->
<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
    <version>4.7.3.6</version>
</plugin>