clarity-over-cleverness

Clarity over cleverness

Rule of thumb

If a competent engineer who has never seen this code needs more than five seconds to understand a line, that line is a candidate for rewrite.

The bar is not "fewer characters". The bar is fewer surprises.

Targets (apply, in order)

1. Untangle nested ternaries

Bad:

return a ? (b ? x : y) : (c ? z : w);

Better:

if (a) {
    return b ? x : y;
}
return c ? z : w;

Best (when shapes line up):

return switch (state) {
    case ACTIVE -> x;
    case PAUSED -> y;
    case CLOSED -> z;
    case PENDING -> w;
};

2. Streams only when they read better than a loop

Bad (clever stream that's actually obscure):

return items.stream()
    .collect(Collectors.toMap(
        Item::id,
        Function.identity(),
        (a, b) -> a.timestamp().isAfter(b.timestamp()) ? a : b));

Better (explicit loop, named purpose):

Map<Id, Item> latestById = new HashMap<>();
for (Item it : items) {
    Item existing = latestById.get(it.id());
    if (existing == null || it.timestamp().isAfter(existing.timestamp())) {
        latestById.put(it.id(), it);
    }
}
return latestById;

(If the team consistently uses streams, follow the team. The point is consistency + readability, not banning streams.)

3. Inline once-used helpers

If a private method has exactly one caller AND the helper name doesn't add information, inline it. Reverse if a long method has a recognizable middle "phase" — extract that phase with a domain-meaningful name.

4. Kill option flags with one used value

Bad:

public Result calculate(Input in, boolean strict, boolean retry, Mode mode) { ... }
// every caller passes (in, true, false, Mode.DEFAULT)

Better: drop the unused dimensions; add them back when a real second caller exists.

5. Replace clever names with domain names

Bad: processX, handleData, doWork. Better: redeemGiftCard, priceWithDiscount, rejectIfExpired.