Nitpicks are for Robots

Fri 09 June 2017 by Moshe Zadka

Many projects and organizations have a coding standard. For Python, much of the time, the standard is a variant of PEP 8. During code reviews, often the reviewer will point out where the code disagrees with the standard, and ask for it to be fixed. Sometimes, if the reviewer is self-aware enough, they will precede those comments with nit or nitpick.

As Raymond Hettinger points out in Beyond PEP8, this gives a reviewer "something to do" without needing a lot of understanding, and will sometimes be used by people who feel overwhelmed at their job. Often these people need to be helped (mentored, tutored or sometimes just encouraged) but those code reviews mask their difficulties with an illusion of productivity.

Moreover, this often feels to the original coder as a put-down attempt ("I know the standard better than you") or simply as an attempt to slow them down and derail them. It does not matter that this is rarely the real intention (although, in sufficiently toxic teams, it can be) it is hard to see a comment on every other line saying "there is a missing space after '3'" or "funcName should be func_name" without feeling that enough is enough, and clearly the reviewer is just trying to make themselves feel important.

The proper solution for that is to automate the nitpicks. There are many possible tools to use there: flake8 (or a custom flake8 plugin), pylint (or a custom pylint plugin) or even, if your needs are unique enough, write a custom tool.

Ideally, there is already CI in place for the tool, using Tox and some CI runner that integrates with your development life cycle (otherwise, how would the unit tests run?) and extending Tox with a new environment for running whatever automatic nitpicker (or nitpickers) should be straightforward.

When adding a new nitpicking rule, some sort of grandfathering strategy needs to be added. My favorite one, unfortunately, takes some time to implement: have Tox run the linting tool, itself, in "ignore process exit code" mode. Capture the output, and compare it to a list of exceptions kept in a special "list of exceptions" file. Now -- and this is the important thing -- any deviation is an error. In particular, anything that fixes a nitpick should also remove it from the list of exceptions.

Of course, this means that it is possible to add to the list of exceptions. But now it is clearly visible in the code diff. The code review will naturally ask "why", since clearly conventions have been intentionally violated. In a rare case, there might be a reason that is good. But the important thing: now the question is not arbitrary, asked by a human with possibly impure motivations -- and so, will be answered in honesty and with good intentions assumed.