The explanation tax

The cost a naive check imposes on documentation. Because a scanner reading raw text cannot tell a mention of a pattern from a use of it, the most thoroughly explained file carries the most surface to be flagged, and a team under a green build learns to write fewer reasons down. The repair is to strip comments before matching on any check whose pattern could plausibly appear in an explanation, and to treat a rule that taxes documentation as a defect in the rule.