What are nits, and why are they bad?

The term "nit" is ubiquitous in engineering for trivial code review comments. But when asking “What is a nit?” definitions vary.

The term “nit" has become too broad, encompassing both stylistic preference and non-blocking comments. I'll look at better models that separate nits from useful suggestions and make the case to eliminate style-based nits through automation. This change in convention helps focus reviews on the substantive conversation. My goal is to spark thoughtful re-examination of processes to help accelerate software development.

The Unclear Definition of "Nit"

Nits are inherently a smell - but for me to make that claim, I need to disambiguate what people mean by nit.

Google’s “Standard of Code Review” defines nits as:

• “Reviewers… expressing that something could be better, but if it’s not very important”

• “purely educational, but not critical… [to] indicate that it’s not mandatory for the author to resolve it in this CL”

The Conventional Comments framework defines nits as:

• “trivial preference-based requests. These should be non-blocking by nature”

The top Google search result for “what is a nit in a code review” claims:

• “A nit is a small, insignificant issue spotted during a code review process that doesn't have a major impact on the overall quality of the code.”

The Chromium glossary defines nits as:

• “a trivial suggestion such as style issues”

When folks defend nits, I suspect they are actually defending “non-blocking” comments - including educational remarks, context sharing, suggestions, aspirations, and more. Poor definitions from Google’s otherwise excellent style guide muddles two orthogonal ideas: non-blocking comments, and trivial preference-based requests. The former is a healthy means of communication between engineers writing code. The latter is an inconsistent inefficiency.

Analyzing Real Nit Comments

To demonstrate that most all nits are wasteful, I analyzed a dataset of 25,000 comments prefixed with "nit" from Graphite. After preprocessing the data, I utilized the BAAI/bge-large-en embedding model to create vector representations of each comment.

I then performed k-means clustering to group the comments into five distinct categories based on their vector similarities. For each cluster, I used llama2:70b to summarize the 100 most centroidal examples into clear themes.

Language inconsistencies

• Spacing, semicolons, parentheses, syntax

• Examples:

  • "nit: missing semicolon after if statement"

  • "nit: remove extraneous parentheses around expression"

Code organization

• Location of functions/variables, descriptive names, modularization

• Examples:

  • "nit: move this utility function into shared utils file"

  • "nit: rename id to customerId for clarity"

Type hints & documentation

• Adding hints and docs for clarity and maintainability

• Examples:

  • "nit: add type hint that this is a string"

  • "nit: document this class with a docstring"

Best practices

• Null checks, naming conventions, code formatting

• Examples:

  • "nit: avoid unnecessary null check here"

  • "nit: use camelCase rather than underscore_case"

Functionality & logic

• Simplifying conditions, algorithms, error handling

• Examples:

  • "nit: use early return rather than nested if"

  • "nit: refactor this complex method for readability"

Notice how wasteful these genres of comments are. The first three categories represent pure stylistic nits relating to consistency and conventions. These could be eliminated through configured auto-formatters, linting, and enforced style guides. Even logic and functionality nits can sometimes be flagged automated by measuring length, number of arguments, indentation, cyclomatic complexity, and more.

At the end of the day, these clustered comments represent a desire for consistent and high-quality style across the codebase. The desire is noble, but the means are misguided. Commenting nits on pull requests:

• Scales linearly with reviewer time

• This leads to inconsistent style bars depending on who is reviewing

• Delivers feedback to authors after they’ve written code, not while

The solution? Encode rules in linters and style guides. Configure code editors to surface issues while folks write code, and double-check that rules are enforced through CI. If you’re afraid of getting your hands dirty writing custom linters for your coding project, I’ve personally had good luck using LLMs to help draft niche-style rules.

Rather than me trying to enumerate great linters myself, I’ll recommend you check out a community-driven list: https://github.com/caramelomartins/awesome-linters. At Graphite, we make heavy use of ESLint, Prettier, and custom rules.

Why wage war on nits?

Comments are expensive. They take time to write, time to read, and time to resolve. They slow down the review cycle and lead to extra iterations on pull requests. Across one million inline comments sampled from Graphite, 6% were explicitly nits. These add up.

The median review cycle for engineers takes 19 hours - fixing comments and re-requesting review slows down engineering velocity dramatically. Even non-blocking nits can pressure engineers into spending an hour adjusting their diff, resubmitting, and re-waiting for CI. The more we can cut down on “trivial” code review comments, the faster engineers can release changes.

When we strip away nits, we increase the signal-to-noise ratio. The remaining comments are a place for engineers to discuss in context - often the best place to share ideas. Reviewing the list of conventional commit types, I see many meaningful categories of discussion: praise, suggestion, issue, todo, question, thought, chore, and note. Many of these ideas are un-automatable. Engineering time is scarce, but the best comments justify the expense. Nits, however, don’t. They are dust that should be brushed off reviews and addressed at the source. Accelerate your team’s software development and automate away nits.