کد تمیز: KISS، DRY، YAGNI و بازآراییClean Code: KISS, DRY, YAGNI & Refactoring

Put a stack of backend job postings side by side and you notice something odd: next to "Spring Boot", "Kafka" and "PostgreSQL" there is almost always one line with no version number and no API — "Clean Code", "SOLID", "familiarity with refactoring". That line is not filler and it is not decoration. The hiring team is measuring one specific thing with it: when somebody has to change the code you wrote six months from now, how long will it take and how likely is something to break?

This chapter is not about beautiful code. It is about cost. A mid-level developer writes code that works; a senior engineer writes code that can be changed safely — and that skill, contrary to popular belief, is not a bag of stylistic preferences. It is a precise technical body of knowledge with named concepts, named catalogues, mechanical techniques and tools you can run in CI.

The site already teaches SOLID and design patterns (solid-patterns), DDD, hexagonal architecture, testing with JUnit and Mockito, and exception mechanics elsewhere. This chapter does not re-teach them; it builds the thing that sits underneath all of them: the daily craft of writing, reading, smelling and refactoring code.

1. Readability is an economic argument, not an aesthetic one

Code is exactly the same. Two measured realities sit behind this entire chapter:

One: code is read far more often than it is written. You write a method once and then read it dozens of times — while debugging, while reviewing, while adding a feature, while responding to an incident. Every second you save in writing and push onto reading comes back multiplied.

Two: the lifetime cost of a system is dominated by maintenance, not initial construction. A successful system lives for years and changes throughout all of them. If initial construction is 20% of total cost, then every decision that makes the code harder to understand and change gets multiplied against the other 80%.

Out of those two comes the conclusion you should be able to state in an interview: "clean code" means optimising for the reader and the changer, not the writer. Any stylistic argument becomes decidable the moment you route it back through that criterion.

Diagram: the cost-of-change feedback loop — نمودار: حلقهٔ بازخورد هزینهٔ تغییر

flowchart LR
    A[Unclear code] --> B[Longer to understand]
    B --> C[Change made<br/>with low confidence]
    C --> D[Defects and rework]
    D --> E[Pressure to ship fast]
    E --> F[Copy-paste and patches]
    F --> A
    C --> G[Tests + refactor]
    G --> H[Clearer code]
    H --> B

The loop has two paths and both are self-reinforcing. The lower path (tests plus refactoring) lowers the cost of understanding; the upper path raises it. What a senior actually does is not write flawless code every time — it is notice which loop the team is on and reverse it.

2. Naming: the highest-leverage daily skill

Naming has the best effort-to-impact ratio in all of software engineering: renaming costs essentially nothing to execute (the IDE does it), yet it can remove the need for a comment, and sometimes for a whole diagram.

2.1 A name must reveal intent

A good name answers three questions: what is this, what does it do, how is it used? If you need a comment to answer those three, the name has failed.

// Before: the names reveal no intent at all
public List<int[]> getThem() {
    List<int[]> list1 = new ArrayList<>();
    for (int[] x : theList) {
        if (x[0] == 4) {           // what does 4 mean?
            list1.add(x);
        }
    }
    return list1;
}

// After: no comment needed, everything is explicit
public List<Cell> flaggedCells() {
    List<Cell> flaggedCells = new ArrayList<>();
    for (Cell cell : gameBoard) {
        if (cell.isFlagged()) {
            flaggedCells.add(cell);
        }
    }
    return flaggedCells;
}

Nothing structural changed — not one if removed, not one loop. Only names and one data type changed, and the code went from encrypted to self-explanatory. That is exactly what "naming is a lever" means.

2.2 The four classic naming failures

Practical rule on name length: name length should be proportional to scope. i inside a three-line loop is perfectly fine; a static field on a public class needs a name that is unique and greppable across the whole repository.

2.3 Problem-domain versus solution-domain names

If a concept belongs to the business, use business language (SettlementBatch, ChargebackWindow). If it belongs to the technology, use technical language (RetryingHttpClient, OrderRepository). Mixing them — OrderManagerHelperImpl — is a sign that you do not know what that class is responsible for either. This is the "ubiquitous language" idea you meet in depth in the DDD chapter; naming is the same idea at the small, everyday scale.

2.4 The special case: naming in a non-English-speaking team

This section is missing from almost every English-language book, yet it is a daily reality for many teams.

Rule one, non-negotiable: identifiers are in English. Not because English is better, but for engineering reasons: the whole ecosystem (frameworks, libraries, logs, error messages) is English, and mixing two languages on one line slows reading; tools and searches work better with one alphabet; and the next person on the team may not speak your language.

Rule two: no transliteration. Identifiers like getMoshtari(), tarikhSodur, mablaghKol are the worst possible case — unreadable to a native speaker of either language and absent from any dictionary.

Rule three, and here is the subtlety: for domain terms with no clean translation, build a team glossary and keep it in the repository. What do you call an accounting document? Voucher? JournalEntry? AccountingDocument? All three are right somewhere. Decide, write it down, and have everyone use the same one. A GLOSSARY.md with two columns (domain term in the local language / approved English identifier) does more for naming consistency than any tool.

Rule four: comments and documentation may be in the local language if the team is monolingual and the decision was made deliberately — but the decision must be uniform. The worst repository is the one where half the comments are in one language and half in another. One important exception: commit messages and Javadoc on shared libraries are better kept in English.

public enum OrderStatus {
    PENDING_PAYMENT,
    PAID,
    SHIPPED,
    CANCELLED
}

3. Comments: which ones smell and which ones earn their place

The key sentence is this: every comment is a small failure of the code to express itself — which is sometimes an unavoidable and completely correct failure.

The logic is simple: a comment is not compiled, not tested, and no tool can guarantee it stayed in sync with the code. So comments drift into lies, and a lying comment is worse than no comment at all.

3.1 Comments that smell

// Bad: restating the code
// if the user is active and has a subscription
if (user.isActive() && user.hasSubscription()) { ... }

// Bad: a comment standing in for a good name
int d; // elapsed time in days

// Bad: a changelog comment — that is git's job
/*
 * 2024-08-03 - A: method added
 * 2024-08-25 - B: rounding bug fixed
 */

// Bad: commented-out code — delete it, git remembers
// processLegacyFormat(payload);

// Bad: ceremonial Javadoc that says nothing
/**
 * Gets the name.
 * @return the name
 */
public String getName() { return name; }

The cure for the first three was in the naming section: if (user.canAccessPremiumContent()), int elapsedTimeInDays;.

3.2 Comments that genuinely earn their place

A good comment answers "why", not "what". The code always states the what; what the code cannot state is intent, an external constraint, and the history of a decision.

// 1) Explaining a non-obvious decision — information that is not in the code
// Provider's API rejects more than 50 IDs per call (documented limit),
// so we chunk here rather than in the caller.
private static final int PROVIDER_BATCH_SIZE = 50;

// 2) Warning of consequences
// NOT thread-safe: SimpleDateFormat keeps mutable state.
// Each call deliberately creates its own instance.

// 3) Explaining a dense regex or algorithm
// Matches IBAN: 2 letters (country) + 2 check digits + up to 30 alphanumerics
private static final Pattern IBAN = Pattern.compile("^[A-Z]{2}\\d{2}[A-Z0-9]{1,30}$");

// 4) A TODO with a ticket and an owner — not an orphan TODO
// TODO(PLAT-4821): remove after the legacy pricing service is decommissioned (Q3).

// 5) Contract Javadoc for a public API: preconditions, postconditions, exceptions
/**
 * Reserves stock for an order.
 *
 * @param orderId non-null identifier of an existing order
 * @return the reservation, never {@code null}
 * @throws InsufficientStockException if any line cannot be fully reserved;
 *         no partial reservation is created in that case
 */

The fifth case matters most: for code other people call (another team, a library consumer), Javadoc is part of the contract, not an extra note. What you must write is what the signature cannot express: is null allowed? Does a failure leave partial effects? Is it thread-safe?

4. Functions: small, single-level, and readable like prose

4.1 Small, and then smaller

The rule is empirical and unforgiving: a function should do one thing; do it well; and do only that. The practical test: if you can extract another function from it whose name is not merely a restatement of the implementation, then the function was doing more than one thing.

4.2 One level of abstraction and the stepdown rule

The biggest single cause of an unreadable function is mixed levels of abstraction: one line talks about a business concept and the next talks about an array index.

The stepdown rule: code should read top-down like prose; each function should call functions exactly one level of abstraction below itself.

// Before: four levels of abstraction in one method
public void processOrder(Order order) {
    if (order == null || order.getLines().isEmpty()) {
        throw new IllegalArgumentException("bad order");
    }
    BigDecimal total = BigDecimal.ZERO;
    for (OrderLine line : order.getLines()) {
        BigDecimal lineTotal = line.getUnitPrice()
                .multiply(BigDecimal.valueOf(line.getQuantity()));
        if (line.getDiscountPercent() > 0) {
            lineTotal = lineTotal.multiply(
                    BigDecimal.ONE.subtract(
                        BigDecimal.valueOf(line.getDiscountPercent())
                                  .divide(BigDecimal.valueOf(100), 4, RoundingMode.HALF_UP)));
        }
        total = total.add(lineTotal);
    }
    if (order.getCustomer().getTier() == Tier.GOLD) {
        total = total.multiply(new BigDecimal("0.95"));
    }
    order.setTotal(total.setScale(2, RoundingMode.HALF_UP));
    jdbcTemplate.update("UPDATE orders SET total = ? WHERE id = ?",
            order.getTotal(), order.getId());
    mailSender.send(order.getCustomer().getEmail(), "Order confirmed", "...");
}

// After: one level per method; it reads like a table of contents
public void processOrder(Order order) {
    validate(order);
    Money total = pricing.priceOf(order);
    order.applyTotal(total);
    orderRepository.save(order);
    notifications.orderConfirmed(order);
}

And one level down:

final class OrderPricing {

    private static final BigDecimal GOLD_TIER_FACTOR = new BigDecimal("0.95");

    Money priceOf(Order order) {
        Money subtotal = order.lines().stream()
                .map(this::priceOfLine)
                .reduce(Money.ZERO, Money::plus);
        return applyTierDiscount(subtotal, order.customerTier());
    }

    private Money priceOfLine(OrderLine line) {
        return line.unitPrice()
                .times(line.quantity())
                .minusPercent(line.discountPercent());
    }

    private Money applyTierDiscount(Money amount, Tier tier) {
        return tier == Tier.GOLD ? amount.times(GOLD_TIER_FACTOR) : amount;
    }
}

Several things improved at once: abstraction levels separated, raw BigDecimal disappeared behind a domain type (Money) — the antidote to primitive obsession you meet in section 7 — the magic number 0.95 got a name, and the body of processOrder can now be read aloud to a business person.

4.3 Argument count

The preferred order is zero > one > two > three. Above three requires justification.

• Zero arguments (niladic): best. Usually means the function operates on the object's own state.
• One argument (monadic): either asks a question (boolean exists(File f)) or transforms something (InputStream open(File f)).
• Two arguments (dyadic): fine when the two values are natural parts of one concept (new Point(x, y)). assertEquals(expected, actual) is poor because the order must be memorised, not inferred.
• Three or more: almost always means several arguments together form one concept and belong in an object → Introduce Parameter Object.

// Bad: the reader must memorise the order, and the compiler cannot help
transfer(fromAccountId, toAccountId, amount, currency, reference, true, false);

// Better: each value's meaning lives in its type
transfer(new TransferCommand(
        AccountId.of(fromAccountId),
        AccountId.of(toAccountId),
        Money.of(amount, currency),
        Reference.of(reference)));

// Bad
public void save(Order order, boolean validate) {
    if (validate) { validator.check(order); }
    repository.persist(order);
}

// Good: the Remove Flag Argument refactoring
public void save(Order order) {
    repository.persist(order);
}

public void validateAndSave(Order order) {
    validator.check(order);
    save(order);
}

4.4 Command-Query Separation (CQS)

CQS: every function either does something (changes state and returns nothing) or answers a question (returns something and changes nothing) — never both.

// Bad: it both asks and mutates. At the call site the reader is lost:
// if (set("username", "admin")) ... means "if it was set" or "if it existed"?
public boolean set(String attribute, String value) { ... }

// Good
if (attributeExists("username")) {
    setAttribute("username", "admin");
}

4.5 Output arguments and hidden side effects

An output argument (void appendFooter(StringBuilder report)) forces the reader to consult the signature to discover what is being mutated. In modern Java it is usually better to return a value and keep inputs immutable. A hidden side effect is worse: a method called checkPassword that also resets the session on the way through. That effect must either be in the name or not happen at all.

5. Error handling as design

The mechanics of exceptions (checked vs unchecked, try-with-resources, the cause chain) belong to the exceptions chapter. Here we look only at the design dimension: errors are part of your API, not an afterthought.

5.1 Exceptions over error codes

Error codes interleave the main logic with error logic and force you to check immediately after every call. Exceptions separate the two.

// Bad: the happy path is buried under error checks
int code = device.shutDown();
if (code == DeviceCode.OK) {
    int c2 = registry.unregister(device);
    if (c2 == DeviceCode.OK) { log.info("done"); }
    else { log.error("unregister failed"); }
} else {
    log.error("shutdown failed");
}

// Good: the happy path is readable, errors handled in one place
try {
    device.shutDown();
    registry.unregister(device);
} catch (DeviceOperationException e) {
    log.error("Could not decommission device {}", device.id(), e);
}

5.2 Extract the body of try/catch

try should be almost the first word of the method, and nothing should follow the catch. The reason is the same "one function, one thing": error handling is itself one thing.

public void delete(Page page) {
    try {
        deletePageAndAllReferences(page);
    } catch (DataAccessException e) {
        throw new PageDeletionFailedException(page.id(), e);
    }
}

private void deletePageAndAllReferences(Page page) {
    pageRepository.delete(page);
    referenceRepository.deleteByPage(page.id());
    searchIndex.remove(page.id());
}

5.3 Define the exception the caller actually needs

The single biggest mistake in exception design is building the hierarchy around the source of the error, when the caller decides based on what it must do next.

// Bad: the caller has to handle three unrelated things that all mean the same
try {
    port.call();
} catch (SocketTimeoutException | ConnectException | SSLHandshakeException e) {
    // all three mean: not right now, retry later
}

// Good: a thin layer translating technical failure into a domain concept
class PaymentGatewayClient {
    PaymentResult charge(ChargeRequest request) {
        try {
            return httpPort.post(request);
        } catch (IOException | SSLException e) {
            throw new PaymentGatewayUnavailableException(request.reference(), e);
        }
    }
}

Now the caller has one decision instead of three. This is the wrapper pattern, and it simultaneously keeps the HTTP library out of your business logic.

5.4 Don't return null, don't pass null

null is not a value; it is a time bomb that carries no information about its origin at the point where it explodes.

// Bad
List<Employee> employees = getEmployees();
if (employees != null) {           // this if is repeated at every call site
    for (Employee e : employees) { ... }
}

// Good: an empty collection, never null
public List<Employee> employees() {
    return employees == null ? List.of() : List.copyOf(employees);
}

For parameters, be explicit at public boundaries:

public Reservation reserve(OrderId orderId, Quantity quantity) {
    Objects.requireNonNull(orderId, "orderId");
    Objects.requireNonNull(quantity, "quantity");
    ...
}

public Optional<Customer> findByEmail(Email email) { ... }

// At the call site — never get()
Customer customer = customers.findByEmail(email)
        .orElseThrow(() -> new CustomerNotFoundException(email));

String label = customers.findByEmail(email)
        .map(Customer::displayName)
        .orElse("unknown");

6. The principles, with real refactorings — not slogans

6.1 KISS and accidental complexity

KISS says "keep it simple". But what does "simple" mean? The precise, usable definition separates essential complexity from accidental complexity.

• Essential complexity comes from the problem itself. Computing VAT with several rate bands really is complicated; no design removes that.
• Accidental complexity is what we add: a layer that adds nothing, an abstraction over a single implementation, configuration that never changes, a framework of which 5% is used.

// Accidental complexity: four types for what one method does
public interface DiscountStrategy { BigDecimal apply(BigDecimal amount); }
public class DiscountStrategyFactory { ... }
public class DefaultDiscountStrategy implements DiscountStrategy { ... }
public class DiscountStrategyConfig { ... }
// and there is exactly one implementation in the whole project

// KISS: until there is a real need to swap implementations
BigDecimal discounted = amount.multiply(GOLD_TIER_FACTOR);

6.2 DRY: duplication of knowledge, not of text

This is the most misunderstood principle in all of software engineering. The precise definition: every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

The operative word is "knowledge", not "text". Two pieces of code that look alike but change for different reasons are not duplication — they are coincidental duplication, and merging them is a future bug.

// These two only *look* the same
BigDecimal invoiceTotal = quantity.multiply(unitPrice);   // invoice amount
BigDecimal shippingCost = weightKg.multiply(ratePerKg);   // shipping cost

If you unify them into multiplyTwoNumbers(a, b) you have centralised no knowledge at all — you have merely glued two independent concepts together. The day shipping becomes "minimum 5 units + weight × rate", you must either pollute the shared function with a boolean (hello, flag argument) or split it apart again.

By contrast, this really is duplicated knowledge:

// The same business rule in three files: "orders under 100,000 pay shipping"
if (order.total().compareTo(new BigDecimal("100000")) < 0) { ... }   // OrderService
if (o.getTotal().doubleValue() < 100000) { ... }                     // CheckoutController
// and in a test: assertTrue(cart.total() < 100_000)

One business rule represented in three places. If the threshold changes and one site is missed, you have a production bug. The cure:

public final class ShippingPolicy {
    private static final Money FREE_SHIPPING_THRESHOLD = Money.of(100_000);

    public boolean qualifiesForFreeShipping(Money orderTotal) {
        return orderTotal.isGreaterThanOrEqual(FREE_SHIPPING_THRESHOLD);
    }
}

Diagram: deciding what to do with duplication — نمودار: تصمیم‌گیری دربارهٔ تکرار

flowchart TD
    A[Two similar pieces of code] --> B{Do they change<br/>for the same reason?}
    B -- No --> C[Coincidental duplication<br/>Leave them separate]
    B -- Yes --> D{Seen it 3 times?}
    D -- No --> E[Wait. Duplicate once more<br/>and learn the shape]
    D -- Yes --> F[Extract the shared knowledge<br/>into one named concept]
    F --> G{Does the abstraction need<br/>a flag or a mode?}
    G -- Yes --> C
    G -- No --> H[Good abstraction]

The Rule of Three: write it once. Duplicate it the second time and be annoyed. Abstract on the third. The reasoning is statistical: with two samples you cannot tell which parts are genuinely shared; with three, the right shape of the abstraction becomes visible.

WET and AHA are the useful counterweights to over-DRYing. WET ("Write Everything Twice", or more sarcastically "We Enjoy Typing") reminds you that a little duplication is cheaper than a wrong abstraction. AHA ("Avoid Hasty Abstractions") states it as a preference: prefer duplication over the wrong abstraction — because duplication is local and removable, whereas a wrong abstraction spreads through the codebase and is expensive to undo.

6.3 YAGNI and speculative generality

YAGNI — "You Aren't Gonna Need It": do not build the capability you do not need now, even when you are sure you will need it later.

The reasoning has three parts: (1) usually you never need it; (2) when you do, it is usually not in the shape you guessed; (3) meanwhile that code must be maintained, tested, read and carried through every build.

Its companion smell is speculative generality: an interface with one implementation, a type parameter that never varies, hooks and events with no listeners, configuration that is always left at default, an abstract class with exactly one subclass.

// Speculative generality: "maybe we will have several providers later"
public interface NotificationChannel { void send(Notification n); }
public class SmsChannel implements NotificationChannel { ... }
public abstract class AbstractNotificationChannel implements NotificationChannel { ... }
public class NotificationChannelRegistry { ... }
public class NotificationChannelProperties { ... }
// and for two years there has only ever been SMS

6.4 The Boy Scout Rule

"Leave the campground cleaner than you found it." Engineering translation: every time you open a file for a ticket, make one small, low-risk improvement too — a better name, an extracted method, a dead comment removed.

Its power is that it is incremental: quality rises without a rewrite project. Its risk is obvious — if your PR touches half the repository, nobody can review it. The practical boundary: the improvement must be inside files you touched for the ticket, and take less than a few minutes; anything bigger deserves its own ticket.

6.5 The Principle of Least Astonishment (POLA)

Code must do what its name promises — no more and no less. If the reader says "wait, what?", you have manufactured a future bug.

// Astonishing: it is called "get" but it writes
public User getUser(String id) {
    User u = cache.get(id);
    if (u == null) {
        u = db.load(id);
        cache.put(id, u);
        auditLog.record("user accessed", id);   // hidden side effect
    }
    return u;
}

In tests this method suddenly depends on a database and an audit sink, and nobody understands why. If caching and auditing are part of the contract, make the name honest: loadAndAuditUser — or better, separate the responsibilities.

6.6 Composition over inheritance

Inheritance mechanics and polymorphism belong to oop-deep, and the Liskov Substitution Principle to solid-patterns. What matters at the daily-craft level:

Inheritance is the strongest coupling in Java — the subclass becomes dependent on the parent's implementation details, and that dependency is locked at compile time. Composition gives you the same reuse with weaker coupling.

// Bad: inheritance for code reuse, not for "is-a"
public class OrderService extends JdbcSupport { ... }   // an OrderService is not a JdbcSupport

// Good: composition — an explicit, swappable dependency
public class OrderService {
    private final OrderRepository orders;
    OrderService(OrderRepository orders) { this.orders = orders; }
}

Rule: use inheritance only when the relationship is genuinely "is-a" and you want the subtype to be substitutable everywhere the parent appears. For "code reuse", pick composition or an interface default method.

6.7 Tell, Don't Ask and the Law of Demeter

Tell Don't Ask: tell an object what to do; do not pull its data out to decide for it.

// Ask: the rule has been dragged out of the object
if (account.getBalance().compareTo(amount) >= 0) {
    account.setBalance(account.getBalance().subtract(amount));
}

// Tell: the rule lives with the data
account.withdraw(amount);   // it checks the balance and throws itself

The first version has three problems: the rule is repeated at every call site (violating DRY), the object cannot guarantee its own invariants, and under concurrency it is a race.

The Law of Demeter — "only talk to your immediate friends": a method should only call methods on itself, its parameters, objects it creates, and its direct fields.

// Violation: a message chain — you depend on the internals of three other objects
String city = order.getCustomer().getAddress().getCity().getName();

// Fix: Hide Delegate — ask the object, not its innards
String city = order.shippingCityName();

6.8 The Single Level of Abstraction principle (SLA)

The summarising rule for this section: within any block of code, every statement should sit at the same level of abstraction. It is the only criterion that makes "which function should I split?" decidable, and it is what drives all the refactorings in section 8.

7. The code-smell catalogue

A code smell is not a bug. It is a surface symptom that usually points at a deeper problem — like a burning smell in a kitchen: not itself the problem, but you go and look.

The senior skill is knowing, for each smell, the refactoring that answers it. The table below is the full map; compact examples follow.

7.1 Primitive obsession and data clumps

// Smell: Primitive Obsession + Data Clumps (these four always travel together)
public void ship(String street, String city, String postalCode, String country,
                 BigDecimal weight, String weightUnit) { ... }

// Cure: two missing concepts finally get names
public record Address(String street, String city, PostalCode postalCode, CountryCode country) {}
public record Weight(BigDecimal value, WeightUnit unit) {
    public Weight {
        if (value.signum() < 0) throw new IllegalArgumentException("weight must be >= 0");
    }
}

public void ship(Address destination, Weight weight) { ... }

The real payoff is not just readability: validation now happens once in the constructor (a record with a compact constructor), accidentally swapping city and country no longer compiles, and related behaviour (address formatting, unit conversion) has a home.

7.2 Feature Envy and the anemic domain model

// Smell: the method lives in OrderService but wants all of Order's data
class OrderService {
    boolean isEligibleForFreeShipping(Order order) {
        return order.getTotal().compareTo(THRESHOLD) >= 0
            && !order.getShippingAddress().isRemote()
            && order.getCustomer().getTier() != Tier.BASIC;
    }
}

// Cure: Move Function — the rule goes to live next to its data
class Order {
    boolean isEligibleForFreeShipping() {
        return total.isGreaterThanOrEqual(FREE_SHIPPING_THRESHOLD)
            && !shippingAddress.isRemote()
            && customerTier != Tier.BASIC;
    }
}

7.3 Temporal coupling

// Smell: an invisible contract — get the order wrong and you get a NullPointerException
Report report = new Report();
report.setTemplate(template);
report.loadData();
report.render();          // forget loadData and it explodes

// Cure: the object is either fully constructed or not constructed at all
Report report = Report.from(template, dataSource);   // factory, valid state guaranteed
String html = report.render();

7.4 Shotgun Surgery versus Divergent Change

These two are mirror images and are constantly confused:

• Shotgun Surgery: one conceptual change → ten files touched. Knowledge is scattered; it must be gathered.
• Divergent Change: one file → changes for three unrelated reasons. Responsibilities are mixed; they must be split.

A Shotgun Surgery example: adding a new payment method requires changing an enum, a switch in a service, another switch in reporting, and an if in the UI. The cure: gather all the knowledge about each payment method into one place (a class, or an enum with behaviour) — which lands you directly on Replace Conditional with Polymorphism.

8. The refactoring catalogue and its iron rule

8.1 The precise definition

Refactoring: changing the internal structure of software to make it easier to understand and cheaper to change, without changing its observable behaviour.

That last clause is everything. If behaviour changed, it was not a refactoring — it was a bug fix, a feature, or (worst case) a new bug. Hence:

Diagram: the small, safe refactoring loop — نمودار: چرخهٔ کوچک و امن بازآرایی

stateDiagram-v2
    [*] --> GreenTests
    GreenTests --> SmallStep: apply ONE refactoring
    SmallStep --> RunTests
    RunTests --> GreenTests: pass -> commit
    RunTests --> Revert: fail
    Revert --> GreenTests: undo, take a smaller step
    GreenTests --> [*]: structure is good enough

8.2 The eleven refactorings that cover 90% of daily work

Guard clauses instead of nesting

// Before: four levels of nesting; the main path is at the bottom of a well
public Money payAmount(Employee e) {
    Money result;
    if (e.isSeparated()) {
        result = Money.ZERO;
    } else {
        if (e.isRetired()) {
            result = retiredAmount();
        } else {
            if (e.isOnLeave()) {
                result = leaveAmount(e);
            } else {
                result = normalPay(e);
            }
        }
    }
    return result;
}

// After: special cases close early, the main path is the last line
public Money payAmount(Employee e) {
    if (e.isSeparated()) return Money.ZERO;
    if (e.isRetired())   return retiredAmount();
    if (e.isOnLeave())   return leaveAmount(e);
    return normalPay(e);
}

Decompose Conditional plus Replace Conditional with Polymorphism

// Before
if (order.getType() == OrderType.EXPORT) {
    tax = base.multiply(BigDecimal.ZERO);
} else if (order.getType() == OrderType.DOMESTIC) {
    tax = base.multiply(new BigDecimal("0.09"));
} else if (order.getType() == OrderType.EXEMPT) {
    tax = BigDecimal.ZERO;
}

// After: each type's knowledge lives with it; adding a type touches one place
public enum OrderType {
    EXPORT  { public Money tax(Money base) { return Money.ZERO; } },
    DOMESTIC{ public Money tax(Money base) { return base.times(VAT_RATE); } },
    EXEMPT  { public Money tax(Money base) { return Money.ZERO; } };

    private static final BigDecimal VAT_RATE = new BigDecimal("0.09");
    public abstract Money tax(Money base);
}

In modern Java the alternative is a sealed interface with a pattern-matching switch, where the compiler checks exhaustiveness — the modern-java chapter covers the mechanics. Choosing between them is a real decision: an enum with behaviour keeps knowledge inside the type (good when the behaviour belongs to the domain); sealed + switch keeps behaviour outside (good when you have several independent operations over the same types and do not want to clutter the type with all of them).

Encapsulate Collection

// Bad: anyone can mutate the internal list and break the order's invariants
public List<OrderLine> getLines() { return lines; }

// Good: mutation only through meaningful operations
public List<OrderLine> lines() {
    return Collections.unmodifiableList(lines);   // or List.copyOf(lines)
}

public void addLine(Product product, Quantity quantity) {
    if (status != OrderStatus.DRAFT) {
        throw new OrderNotEditableException(id, status);
    }
    lines.add(new OrderLine(product, quantity));
}

Separate Query from Modifier

// Bad: it both looks up and raises an alarm
public Customer findCustomerAndNotifyIfBlocked(Email email) { ... }

// Good
Customer customer = customers.require(email);
if (customer.isBlocked()) {
    alerts.blockedCustomerAccessAttempt(customer.id());
}

8.3 Preparatory refactoring

One of the most useful practical ideas: when adding a feature is hard in the current structure, first change the structure so the addition becomes easy, then add it. The famous metaphor: if you want to go a hundred kilometres east but the road runs north, first get onto the right road.

It also pays off in review: the first PR has no behaviour change at all and is approved quickly; the second is small and focused.

8.4 Clean code is not only Java: readable SQL

The same principles apply to SQL: naming, one level of abstraction per step, and no magic numbers. Compare:

-- Before: nested, unnamed steps with a magic threshold
SELECT c.name, SUM(o.total_amount)
FROM customers c
JOIN orders o ON o.customer_id = c.id
WHERE c.status = 'ACTIVE'
  AND o.placed_at >= now() - INTERVAL '90 days'
GROUP BY c.name
HAVING SUM(o.total_amount) > 1000;

-- Before: the same shape in Oracle; SYSTIMESTAMP replaces now()
SELECT c.name, SUM(o.total_amount)
FROM customers c
JOIN orders o ON o.customer_id = c.id
WHERE c.status = 'ACTIVE'
  AND o.placed_at >= SYSTIMESTAMP - INTERVAL '90' DAY
GROUP BY c.name
HAVING SUM(o.total_amount) > 1000;

The refactored version with CTEs, where every step has a name (the SQL equivalent of Extract Function):

WITH active_customers AS (
    SELECT c.id, c.name
    FROM customers c
    WHERE c.status = 'ACTIVE'
),
orders_in_window AS (
    SELECT o.customer_id, o.total_amount
    FROM orders o
    WHERE o.placed_at >= now() - INTERVAL '90 days'
)
SELECT ac.name,
       SUM(oiw.total_amount) AS total_spent
FROM active_customers ac
JOIN orders_in_window oiw ON oiw.customer_id = ac.id
GROUP BY ac.name
HAVING SUM(oiw.total_amount) > 1000;

WITH active_customers AS (
    SELECT c.id, c.name
    FROM customers c
    WHERE c.status = 'ACTIVE'
),
orders_in_window AS (
    SELECT o.customer_id, o.total_amount
    FROM orders o
    WHERE o.placed_at >= SYSTIMESTAMP - INTERVAL '90' DAY
)
SELECT ac.name,
       SUM(oiw.total_amount) AS total_spent
FROM active_customers ac
JOIN orders_in_window oiw ON oiw.customer_id = ac.id
GROUP BY ac.name
HAVING SUM(oiw.total_amount) > 1000;

9. Working with legacy code: changing code you are afraid of

The blunt, widely adopted industry definition: legacy code is code without tests. Age, language and framework are irrelevant; what makes code legacy is that you cannot change it with confidence.

And here is the vicious circle: to change safely you need tests; to write tests you usually have to change the code (because it is untestable). The techniques below are the way out.

Diagram: the algorithm for changing legacy code safely — نمودار: الگوریتم تغییر امن در کد legacy

flowchart TD
    A[Change request] --> B{Tests cover<br/>this behaviour?}
    B -- Yes --> C[Refactor, then change]
    B -- No --> D{Can I test it<br/>as-is?}
    D -- Yes --> E[Write characterization tests]
    E --> C
    D -- No --> F[Find or create a seam<br/>minimal, reviewed change]
    F --> E
    D -- Too risky --> G[Sprout method / Sprout class<br/>or Wrap method]
    G --> H[New code is tested,<br/>old code untouched]

9.1 Characterization tests

A normal test says "the code should do this". A characterization test says "the code currently does this". The distinction is crucial: you are locking in current behaviour — right or wrong — so your refactoring does not alter it.

The practical technique:

@Test
void characterize_legacyInvoiceTotal() {
    LegacyInvoiceCalculator calc = new LegacyInvoiceCalculator();

    // 1) Write a deliberately wrong assertion to discover the real value
    // assertThat(calc.total(sampleInvoice())).isEqualByComparingTo("0");
    // test output: expected 0 but was 1234500

    // 2) Record the real value — this is not "correct", it is "current"
    assertThat(calc.total(sampleInvoice())).isEqualByComparingTo("1234500");
}

An important cultural note: mark these tests clearly by name and comment (characterize_*) so nobody mistakes them for a business specification. If it later turns out the current behaviour is a bug, the test changes — and that change is a deliberate decision, not an accident.

For legacy code with large outputs (JSON, reports, files), approval testing is the more practical variant: store the output in an "approved" file and diff against it.

9.2 Seams: places where you can change behaviour without editing code

A seam is a place in the program where you can alter behaviour from outside without editing at that point. In Java the most important kind is the object seam: a place where a dependency is swappable through polymorphism.

// Before: no seam at all — the dependency is constructed inside the method
public class OrderProcessor {
    public void process(Order o) {
        PaymentGateway gw = new HttpPaymentGateway("https://prod...");  // untestable
        gw.charge(o.total());
    }
}

// After: the smallest change that creates a seam — constructor injection
public class OrderProcessor {
    private final PaymentGateway gateway;

    public OrderProcessor(PaymentGateway gateway) {   // seam
        this.gateway = gateway;
    }

    public void process(Order o) {
        gateway.charge(o.total());
    }
}

If even that is risky (there are dozens of new OrderProcessor() call sites), the more conservative technique is "extract and override for test": move the construction into a protected method and, in the test, subclass and override it. It is ugly, but it carries the least risk and is a stepping stone.

9.3 Sprout and Wrap: when you do not want to touch the old code at all

Sprout Method / Sprout Class: write the new capability as new, fully tested code and add exactly one call line to the old code.

public void postEntries(List<Entry> entries) {
    // ... 200 lines of untested legacy code ...

    validateAgainstFiscalCalendar(entries);   // <- the only new line (sprout)

    // ... 100 more lines ...
}

// New class, fully tested, independent
final class FiscalCalendarValidator { ... }

Wrap Method: when the new behaviour must run before or after existing behaviour, rename the old method and create a new one with the old name that calls both.

// Step 1: rename the original (with the IDE — safe)
private void postEntriesInternal(List<Entry> entries) { /* old code, untouched */ }

// Step 2: a new method with the old name — callers notice nothing
public void postEntries(List<Entry> entries) {
    postEntriesInternal(entries);
    auditTrail.recordPosting(entries);   // new, testable behaviour
}

Wrap Class is the same idea one level up (the Decorator pattern): a new class implementing the same interface, holding the old one and adding behaviour — without a single line changed in the old class.

10. Technical debt: a ledger, not an excuse

The "debt" metaphor is more precise than it looks: like a loan, technical debt can be the right decision (you get capital you need now) provided it is recorded and you know the interest rate. What makes it toxic is debt that is unintentional and invisible.

10.1 The four quadrants

Diagram: the technical debt quadrant — نمودار: چهار ربع بدهی فنی

flowchart TD
    subgraph Deliberate
      A["Prudent + Deliberate<br/>'Ship now, we know the cost'<br/>-> record it, schedule payback"]
      B["Reckless + Deliberate<br/>'No time for design'<br/>-> the dangerous one"]
    end
    subgraph Inadvertent
      C["Prudent + Inadvertent<br/>'Now we know how we should<br/>have done it'<br/>-> normal learning"]
      D["Reckless + Inadvertent<br/>'What is layering?'<br/>-> a skill gap, not debt"]
    end

• Deliberate and prudent: "We know the right way, but to hit this launch date we take a shortcut and repay it next sprint." This is correct debt.
• Deliberate and reckless: "We don't have time for design." This is where systems die.
• Inadvertent and prudent: "Now that it's finished, we understand how we should have built it." This is normal learning and unavoidable — the main source of healthy refactoring.
• Inadvertent and reckless: the team does not know what layering is. That is not debt, it is a skill gap, and the cure is teaching and review, not a ticket.

10.2 Making debt visible

Invisible debt always gets translated as "the developers have got slower". Three tools make it visible:

1. A debt register: real tickets in the same product backlog, in the same format. Each item needs three things: impact ("any pricing change takes two days because the rule is duplicated in three places"), risk ("financial inconsistency"), and cost to repay ("three days").
2. TODO comments carrying a ticket id — plus a lint rule that fails the build on a TODO without one.
3. A number from a tool: SonarQube computes a "technical debt ratio" and remediation effort; use it as a trend, never as an absolute target.

10.3 Paying it down

Three patterns that work:

• Continuous Boy Scouting: the best return for the least risk, and it needs no negotiation.
• A fixed budget: a stated percentage of each sprint's capacity (say 10–20%) goes to debt. The advantage is that the negotiation happens once instead of every sprint.
• Opportunistic repayment: when a feature needs to touch the indebted area, fold preparatory refactoring into that feature's estimate. This is the most natural and least friction-generating route.

11. Code review that improves both the code and the people

Bad review takes one of two forms: "LGTM" in thirty seconds (useless), or thirty comments about whitespace (destructive). Both have the same root cause: no ordering and no automation.

11.1 What to look at, in what order

Order matters because attention is finite. Start with nits and your capacity is gone before you reach the design.

11.2 Feedback that lands

A handful of practical rules that make a real difference:

• Talk about the code, not the person. "This method does three things" instead of "you wrote this badly".
• Label the level. Prefix comments: nit: (taste, free to ignore), question: (I don't understand), suggestion: (better but optional), blocking: (I won't merge until this is resolved). It is a tiny change with the biggest cultural effect, because it removes the ambiguity of "is this mandatory?".
• Give the reason, not just the verdict. "Convert this to Money" is weak; "double introduces rounding error for money and it accumulates across sums" teaches.
• Say the good things too. One sentence — "nice catch on that boundary case in the test" — costs nothing and changes the tone of the whole review.
• When the thread gets long, leave the text. More than three round-trips on one topic means it is time for a five-minute call.

11.3 Review size and latency

Two operational numbers that matter more than any checklist:

• Size: large PRs do not get reviewed, they get rubber-stamped. Above a few hundred lines the quality of findings falls sharply and the "LGTM" rate rises. If your change is big, break it into a chain: refactoring first, feature second.
• Latency: a PR that waits a day loses its author's context, and the author starts working in parallel — which produces more branches and more conflicts. A team agreement like "every PR gets first feedback within half a working day" contributes more to quality than any style rule.

Diagram: the path of a change from commit to merge — نمودار: مسیر یک تغییر از commit تا merge

sequenceDiagram
    participant Dev as Developer
    participant CI as CI pipeline
    participant Rev as Reviewer
    Dev->>CI: push branch
    CI->>CI: format check, lint, static analysis
    CI->>CI: tests + coverage on new code
    CI-->>Dev: fast feedback (style, obvious bugs)
    Dev->>Rev: open PR (small, one intent)
    Rev->>Rev: correctness -> security -> design -> tests -> naming
    Rev-->>Dev: blocking / suggestion / nit
    Dev->>CI: push fixes
    CI-->>Rev: green + quality gate passed
    Rev->>Dev: approve, merge

11.4 Let the machine say the machine things

The right division of labour:

If humans are still arguing about whitespace, the team's problem is not culture — it has no tooling. The next section is exactly that tooling.

12. Tooling in the Java world

The goal of this section is one thing: humans review design, machines review style and bug patterns. Versions reflect the state of the ecosystem in mid-2026; check Maven Central before you copy them.

12.1 The tool map

12.2 Spotless: end the style argument forever

The first tool to add. Reason: it removes the most review friction for the least debate.

<plugin>
  <groupId>com.diffplug.spotless</groupId>
  <artifactId>spotless-maven-plugin</artifactId>
  <version>3.9.0</version>
  <configuration>
    <!-- On an existing project: only files changed relative to main -->
    <ratchetFrom>origin/main</ratchetFrom>
    <java>
      <googleJavaFormat>
        <version>1.28.0</version>
        <style>GOOGLE</style>
      </googleJavaFormat>
      <removeUnusedImports/>
      <formatAnnotations/>
    </java>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>check</goal>
      </goals>
    </execution>
  </executions>
</plugin>

mvn spotless:apply    # auto-fix
mvn spotless:check    # verify only; this is what CI runs

ratchetFrom is the key to adoption on existing projects: instead of one gigantic commit that destroys the whole git blame history, only changed files get reformatted.

12.3 Checkstyle

An important detail many people miss: maven-checkstyle-plugin has its own version and the Checkstyle engine bundled inside it is old; you must upgrade it explicitly.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-checkstyle-plugin</artifactId>
  <version>3.6.0</version>
  <dependencies>
    <!-- Without this, the plugin's old default Checkstyle is used -->
    <dependency>
      <groupId>com.puppycrawl.tools</groupId>
      <artifactId>checkstyle</artifactId>
      <version>13.10.0</version>
    </dependency>
  </dependencies>
  <configuration>
    <configLocation>build/checkstyle.xml</configLocation>
    <consoleOutput>true</consoleOutput>
    <failsOnError>true</failsOnError>
    <violationSeverity>warning</violationSeverity>
    <includeTestSourceDirectory>true</includeTestSourceDirectory>
  </configuration>
  <executions>
    <execution>
      <id>checkstyle-validate</id>
      <phase>validate</phase>
      <goals><goal>check</goal></goals>
    </execution>
  </executions>
</plugin>

A small, realistic configuration containing only rules relevant to this chapter:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
  "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
  "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
  <property name="severity" value="warning"/>

  <module name="TreeWalker">
    <!-- Small functions -->
    <module name="MethodLength">
      <property name="max" value="60"/>
    </module>
    <module name="ParameterNumber">
      <property name="max" value="4"/>
    </module>
    <!-- Complexity -->
    <module name="CyclomaticComplexity">
      <property name="max" value="10"/>
    </module>
    <module name="NPathComplexity">
      <property name="max" value="200"/>
    </module>
    <!-- Naming -->
    <module name="MethodName"/>
    <module name="ConstantName"/>
    <module name="LocalVariableName"/>
    <!-- Magic numbers -->
    <module name="MagicNumber">
      <property name="ignoreNumbers" value="-1, 0, 1, 2"/>
    </module>
    <!-- Real traps -->
    <module name="EqualsHashCode"/>
    <module name="IllegalCatch"/>
    <module name="EmptyCatchBlock"/>
    <module name="TodoComment">
      <!-- A TODO must carry a ticket id -->
      <property name="format" value="TODO(?!\([A-Z]+-\d+\))"/>
    </module>
  </module>
</module>

Checkstyle also ships three standard configurations (sun_checks.xml, google_checks.xml and openjdk_style.xml) which make a good starting point, though almost no team uses them untouched.

12.4 PMD and CPD (copy-paste detection)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-pmd-plugin</artifactId>
  <version>3.28.0</version>
  <configuration>
    <rulesets>
      <ruleset>/category/java/bestpractices.xml</ruleset>
      <ruleset>/category/java/errorprone.xml</ruleset>
      <ruleset>/category/java/design.xml</ruleset>
    </rulesets>
    <printFailingErrors>true</printFailingErrors>
    <minimumTokens>100</minimumTokens>   <!-- CPD threshold -->
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>check</goal>
        <goal>cpd-check</goal>
      </goals>
    </execution>
  </executions>
</plugin>

cpd-check connects directly to the DRY discussion: it finds copy-pasted blocks. But remember that CPD sees textual similarity, not duplicated knowledge — so read its output as a list to investigate, not as a list of mandatory fixes.

12.5 SpotBugs

It works on bytecode, so it sees things textual analysis cannot.

<plugin>
  <groupId>com.github.spotbugs</groupId>
  <artifactId>spotbugs-maven-plugin</artifactId>
  <version>4.10.3.0</version>
  <configuration>
    <excludeFilterFile>build/spotbugs-exclude.xml</excludeFilterFile>
    <xmlOutput>true</xmlOutput>
    <plugins>
      <plugin>
        <groupId>com.h3xstream.findsecbugs</groupId>
        <artifactId>findsecbugs-plugin</artifactId>
        <version>1.14.0</version>
      </plugin>
    </plugins>
  </configuration>
  <executions>
    <execution>
      <goals><goal>check</goal></goals>
    </execution>
  </executions>
</plugin>

An exclusion file for findings you consciously accept:

<FindBugsFilter>
  <Match>
    <Class name="~.*Entity"/>
    <Bug pattern="EI_EXPOSE_REP,EI_EXPOSE_REP2"/>
  </Match>
</FindBugsFilter>

12.6 Error Prone: bug hunting at compile time

The strongest feedback is the fastest feedback. Error Prone rides on javac itself as a plugin, so findings arrive at compile time and many of them carry automatic fixes.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.14.0</version>
  <configuration>
    <compilerArgs>
      <arg>-XDcompilePolicy=simple</arg>
      <arg>--should-stop=ifError=FLOW</arg>
      <arg>-Xplugin:ErrorProne -Xep:MissingOverride:ERROR -Xep:NullAway:ERROR</arg>
      <arg>-XDaddTypeAnnotationsToSymbol=true</arg>
    </compilerArgs>
    <annotationProcessorPaths>
      <path>
        <groupId>com.google.errorprone</groupId>
        <artifactId>error_prone_core</artifactId>
        <version>2.50.0</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

12.7 SonarQube and the quality gate on "new code"

The most practically important idea in recent SonarQube versions is Clean as You Code: the gate applies almost entirely to new code — whatever has been added or changed since a defined baseline.

Why does that matter? Because in a 200,000-line project, demanding that ten thousand pre-existing issues be fixed is impossible, and in practice it makes teams switch the gate off. "Your new code must be clean", however, is entirely achievable — and the arithmetic works: as time passes and files get touched, the clean share of the codebase rises.

mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:5.7.0.6970:sonar \
  -Dsonar.projectKey=my-service \
  -Dsonar.host.url=https://sonar.example.internal \
  -Dsonar.token=$SONAR_TOKEN

Typical conditions for a healthy gate, all on new code: coverage at least 80%, duplicated lines under 3%, no new issues introduced, and acceptable security/maintainability ratings. You must also choose the New Code definition — usually "previous version" or "last N days" — because without a baseline the new-code conditions are meaningless.

12.8 ArchUnit: architecture rules as tests

Architectural decisions that live only in a wiki get violated within months. ArchUnit turns them into tests.

<dependency>
  <groupId>com.tngtech.archunit</groupId>
  <artifactId>archunit-junit5</artifactId>
  <version>1.5.0</version>
  <scope>test</scope>
</dependency>

import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.library.GeneralCodingRules;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

@AnalyzeClasses(packages = "com.example.shop")
class ArchitectureTest {

    @ArchTest
    static final ArchRule layers = layeredArchitecture()
            .consideringOnlyDependenciesInLayers()
            .layer("Web").definedBy("..web..")
            .layer("Application").definedBy("..application..")
            .layer("Domain").definedBy("..domain..")
            .layer("Persistence").definedBy("..persistence..")
            .whereLayer("Web").mayNotBeAccessedByAnyLayer()
            .whereLayer("Application").mayOnlyBeAccessedByLayers("Web")
            .whereLayer("Persistence").mayOnlyBeAccessedByLayers("Application");

    @ArchTest
    static final ArchRule domainStaysPure = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("org.springframework..", "jakarta.persistence..");

    @ArchTest
    static final ArchRule noCycles = slices()
            .matching("com.example.shop.(*)..")
            .should().beFreeOfCycles();

    @ArchTest
    static final ArchRule noFieldInjection =
            GeneralCodingRules.NO_CLASSES_SHOULD_USE_FIELD_INJECTION;

    @ArchTest
    static final ArchRule noStandardStreams =
            GeneralCodingRules.NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS;

    @ArchTest
    static final ArchRule servicesAreNamedProperly = classes()
            .that().resideInAPackage("..application..")
            .and().areAnnotatedWith(org.springframework.stereotype.Service.class)
            .should().haveSimpleNameEndingWith("Service");
}

For an existing project that already has a thousand violations, FreezingArchRule freezes the current violations and only fails on new ones — the Clean as You Code philosophy applied at the architecture level:

import com.tngtech.archunit.library.freeze.FreezingArchRule;

@ArchTest
static final ArchRule frozenLayers = FreezingArchRule.freeze(
        noClasses().that().resideInAPackage("..domain..")
                   .should().dependOnClassesThat().resideInAPackage("..web.."));

# src/test/resources/archunit.properties
freeze.store.default.path=archunit_store
freeze.store.default.allowStoreCreation=true

12.9 Wiring it all into CI

# Example: the quality stages of a pipeline (GitHub Actions syntax)
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0          # required for ratchetFrom and "new code"
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: '25'
          cache: maven
      - name: Format + static analysis + tests
        run: mvn -B verify        # spotless, checkstyle, pmd, spotbugs, tests, jacoco
      - name: SonarQube
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: >
          mvn -B org.sonarsource.scanner.maven:sonar-maven-plugin:5.7.0.6970:sonar
          -Dsonar.projectKey=my-service

13. Senior judgment: when to break these rules

13.1 Rules that should be broken

Every rule in this chapter is a tool for lowering the cost of change. Where the cost of change is not the issue, the rule is not the issue either.

13.2 Consistency with the surroundings beats personal preference

This is probably the most important lesson in the chapter for someone newly senior.

If you join a codebase that uses one pattern everywhere — even a pattern you dislike — and you introduce the "better" pattern in your own file, the net result is negative: the codebase now has two patterns and readers must know both. Inconsistency creates cognitive cost, and that cost usually exceeds the benefit of the better pattern.

The right path: write in the existing style; if you genuinely believe there is a better pattern, raise it as a team decision (an ADR), and if it is accepted, provide a migration path. Changing style through a unilateral PR is neither accepted nor durable.

13.3 How interviewers probe this skill

Three common formats:

1) A code review exercise. They hand you 50–150 lines and ask for your comments. What is actually assessed: do you have an order? A weak candidate opens with formatting and variable names; a strong one first asks what the code is supposed to do, then goes to correctness and edge cases (nulls, concurrency, error handling, unclosed resources), then design, and readability last — explicitly saying "these are nits and should be automated in CI".

2) A refactoring kata. They give you a smelly class and ask you to improve it. What is assessed: do you ask about tests first? Do you take small steps and run the tests between them? Do you know the name of the refactoring you are applying ("I'll do Introduce Parameter Object here") — because knowing the name proves you know the catalogue rather than shuffling code at random.

3) A judgment question. "When would you keep duplicated code?", "When would you not write tests?", "When would you deliberately take on technical debt?" These are the senior filters: a dogmatic answer ("I always write tests") scores lower than a conditional one.