Naming & Function Design
Names are the API you present to every future reader. Units, roles, side effects — and function design judged by responsibility rather than line count.
A name is the interface every future reader uses instead of the body. It has to carry domain meaning, role, units and whether calling it changes anything.
A bare number carries no unit, so the unit lives in someone's head. Three rungs — comment, suffix, type — with escalating cost and escalating safety.
`sendEmail(user, true, false)` is unreadable at the call site, and the call site is where every future reader meets it. The fix is a type, not a comment.
A function is judged by what it needs, what it returns, what it changes, how many reasons it has to change, and whether its name is true. Length is not on the list.
Long is not automatically bad. Ask whether it mixes responsibilities, whether the control flow can be followed, and whether it hides concepts that deserve names.
When code uses the words the business uses, a reader can apply domain knowledge instead of tracing execution. That is the difference between reading and deducing.