Code review and standards

A written standard is a citable standard

I work in a landscape with a formalized code standard: dozens of written rules for backend and frontend, versioned and available in the repositories. I take part in maintaining that set.

The difference between a written standard and an agreed one is what happens in review. With a written rule, the note is “this goes against rule X, which literally says Y”. Without it, it is “I would do it differently”, and then the discussion becomes about who has more seniority, not about what is better for the code.

How I review

• I group by rule, not by file. Deciding “all seven cases of X” is one decision; deciding file by file is seven discussions about the same thing
• I quote the rule literally, with the file where it lives
• I separate what is a rule from what is an opinion. If it is not written, it is marked as a suggestion, not as a non-conformity
• I say what I could not evaluate. A file that is too large, a rule that depends on context I do not have: silence about that is worse than the gap
• I do not change anything without confirmation. Review points out; the author decides

When the rule looks wrong

It happens. In that case I do not force the code to obey in silence, nor ignore it in silence: I point out that the rule looks unfit for the case, say why, and the discussion becomes about the rule. A rule nobody questions becomes bureaucracy; a rule anyone ignores is not a rule.

Automating the mechanical part

Part of the rules can be checked by a tool and runs as an automatic check before the commit. What is left for human review is what requires judgment: modeling, naming, boundaries of responsibility. Spending human attention on what the computer solves is waste on both sides.

Writing a rule to be read by a machine has demands of its own, and they are in A standard the machine consumes.