Refactor clever code instead of explaining it

How to do it

Replace bit tricks and dense one-liners with named steps. Pull a condition into a function whose name states the question, such as isEligibleForRefund. Name the parts of a long expression with local variables. Prefer a clear loop over a chain nobody can follow.

Example

// Bad: a clever line and a note to decode it
// true if the order is paid and shipped but not refunded
const ok = (o.flags & 6) === 6 && !(o.flags & 8);

// Good: the names say it
const isPaid = order => order.flags.has('paid');
const isShipped = order => order.flags.has('shipped');
const isRefunded = order => order.flags.has('refunded');
const isComplete = order => isPaid(order) && isShipped(order) && !isRefunded(order);

# Bad
# skip weekends
days = [d for d in days if d.weekday() < 5]

# Good
def is_weekday(day): return day.weekday() < 5
working_days = [day for day in days if is_weekday(day)]

How to check

Reviewers ask one question for each comment that explains how code works. "Would a rename or an extracted function make this comment unneeded?" If yes, the review fails until the code is changed.