luismori.

Engineering Practices

Code Review Pull Requests Engineering Culture

El bucle infinito de los nits en los PR: ¿realmente necesitamos pull requests perfectos?

Una guía práctica para ingenieros sobre cuándo ayudan los comentarios de tipo nit, cuándo se convierten en ruido y cuántos son suficientes antes de que el equipo deba automatizar, aprobar o sacar la discusión del PR.

18 min de lectura

TL;DR

Los comentarios de tipo nit solo son útiles cuando señalan detalles pequeños, son explícitos y opcionales.

Las mejores recomendaciones que encontré coinciden en lo siguiente:

  • Un PR no necesita ser perfecto. Necesita mejorar la salud del código.
  • Si un comentario es sobre un detalle de pulido, etiquétalo claramente como nit:, optional: o suggestion (non-blocking):.
  • Si los únicos comentarios pendientes son nits, aprueba el PR.
  • Si un nit se repite con frecuencia, deja de escribir el comentario y automatízalo con un formateador, linter, plantilla o guía de estilo.
  • Si una revisión tiene más de un par de nits, agrúpalos en un solo comentario o pregúntate si el equipo realmente está revisando lo que importa.

Mi regla práctica:

0 nits: best default
1-2 nits: okay if clearly optional
3+ nits: batch, automate, or convert into team guidance
only nits left: approve
new nits after fixes: usually stop

No es una ley universal. Es una regla de trabajo que coincide con el espíritu de las recomendaciones de Google, Microsoft, Conventional Comments y varios artículos de profesionales: reservar la atención de quienes revisan para la corrección, el diseño, las pruebas, la seguridad y la mantenibilidad.

Qué aprenderás aquí

  • Qué es un comentario de tipo nit y por qué genera tantos ciclos en los PR.
  • Por qué el «PR perfecto» es un objetivo equivocado para una revisión.
  • Qué dicen las recomendaciones de Google, Microsoft, Conventional Comments y distintos profesionales.
  • Una respuesta práctica a «¿cuántos nits son suficientes?».
  • Cómo pueden quienes revisan separar los bloqueantes de los detalles opcionales de pulido.
  • Cómo pueden responder los autores sin convertir cada preferencia en otro commit.
  • Cómo automatizar los nits repetidos para que las personas revisen lo importante.

El bucle de nits en los PR

La mayoría de los equipos conoce este ciclo:

author opens PR
  |
  v
reviewer leaves useful comments + 8 tiny preferences
  |
  v
author fixes everything
  |
  v
reviewer rereads and finds 5 new tiny preferences
  |
  v
author fixes again
  |
  v
another reviewer adds different tiny preferences
  |
  v
PR waits, context decays, frustration grows

El problema no es que a quienes revisan les importe la calidad. Debe importarles.

El problema es que la revisión ha perdido su orden de prioridades. Un error de seguridad, una prueba faltante, una preferencia de nombres y una línea en blanco llegan como la misma notificación de GitHub. Si todo parece obligatorio, el autor trata todo como obligatorio. Si todo es obligatorio, el PR no puede terminar.

Así es como los equipos convierten accidentalmente la revisión en una búsqueda del diff perfecto.

¿Qué es un nit?

Un nit es un detalle menor de pulido. Por lo general, tiene que ver con nombres, redacción, formato, legibilidad o una pequeña simplificación.

Un buen nit:

nit (non-blocking): I would rename `data` to `invoiceRows` so the next reader
knows what shape this has. Fine to keep as-is if you prefer this name.

Un mal nit:

Rename this.

El primer comentario le indica al autor la prioridad y la intención, y le deja decidir. El segundo genera ambigüedad. ¿Es un bloqueante? ¿Una preferencia? ¿Una convención del equipo? ¿Una solicitud de un mantenedor que debe cumplirse?

En esa ambigüedad crecen los bucles de los PR.

La trampa del PR perfecto

El estándar de revisión de código de Google es la fuente más clara que encontré. Dice que quienes revisan deben inclinarse por aprobar un cambio cuando este mejora claramente la salud general del código del sistema, aunque no sea perfecto.

Esa frase importa porque separa dos objetivos:

good review goal:
  improve the system over time

bad review goal:
  remove every possible imperfection from this PR

«Perfecto» suena responsable, pero a menudo oculta un costo:

  • El PR permanece abierto más tiempo.
  • El autor tiene que seguir cambiando de contexto para volver a un trabajo anterior.
  • Quienes revisan dedican su atención a preferencias en lugar de defectos.
  • Los comentarios importantes quedan enterrados entre comentarios de poco valor.
  • El equipo aprende que la revisión es un costo de negociación, no un sistema de calidad.

La mejor pregunta para una revisión no es:

¿Puedo imaginar una mejora más?

Es:

¿Este cambio es seguro, comprensible, está suficientemente probado y es mejor que lo que teníamos?

Qué dicen las buenas prácticas

Este es un resumen de las fuentes, en lenguaje sencillo.

Las prácticas de ingeniería de Google dicen que no existe el código perfecto, sino un código mejor. Quienes revisan no deberían exigir que se resuelva cada pequeño detalle de pulido antes de aprobar. Si un comentario no es muy importante, recomiendan anteponer Nit: para que el autor sepa que es opcional.

Las recomendaciones de Google sobre comentarios también sugieren etiquetar su nivel de gravedad. Sus ejemplos incluyen Nit:, Optional y FYI, precisamente para ayudar a los autores a entender qué importa y evitar que traten cada comentario como obligatorio.

El Engineering Fundamentals Playbook de Microsoft dice que las personas que revisan deben centrarse en la lógica de negocio, las pruebas, la arquitectura, el diseño, la legibilidad, la mantenibilidad y los errores comunes. También recomienda anteponer Nit: a un «detalle de pulido» y usar herramientas automatizadas de estilo como Black y Prettier.

Conventional Comments hace que la misma idea sea más sistemática. Define nitpick: como algo trivial, basado en preferencias y no bloqueante por naturaleza. También admite modificadores como (blocking) y (non-blocking) para que la intención de la revisión sea visible.

«Deja de señalar detalles menores en las revisiones de código», de Dan Lew, no es un estándar oficial, pero es un relato útil desde la práctica. Su argumento más contundente: muchos nits reducen la relación señal-ruido. Es más fácil pasar por alto un problema crítico cuando está rodeado de una docena de comentarios menores.

El estudio de SmartBear/Cisco sobre revisiones ligeras trata sobre el tamaño de las revisiones y la atención, no específicamente sobre los nits. Aun así, respalda la misma preocupación operativa: la atención de quienes revisan es limitada. El estudio recomienda revisar menos de 200-400 líneas a la vez y mantener las sesiones de revisión en torno a 60-90 minutos. Si la atención es limitada, dedicarla a comentarios repetidos de pulido tiene un costo de oportunidad real.

Lo que dicen las fuentes y lo que infiero

Algunas afirmaciones están respaldadas directamente por las fuentes:

  • Etiquetar la gravedad de los comentarios.
  • Marcar los detalles de pulido como Nit: u opcionales.
  • No buscar código perfecto antes de aprobar.
  • Usar automatización para las reglas objetivas de estilo.
  • Mantener las revisiones lo suficientemente pequeñas para que las personas puedan hacerlas bien.

Otras son inferencias mías a partir de las fuentes y de la práctica de ingeniería:

  • Más de dos comentarios de tipo nit suelen ser una señal de alerta.
  • Por lo general, conviene omitir los nits nuevos después de una ronda de correcciones, a menos que revelen un problema real de mantenibilidad.
  • Los nits repetidos deberían convertirse en automatización o en una guía para el equipo.
  • Si quien revisa quiere cambiar muchas preferencias menores, el verdadero problema puede ser que no está claro quién define el estilo.

Esa distinción importa. No encontré un estándar universal serio que diga «se permiten exactamente N nits». Una mejor respuesta es una política que proteja el flujo de trabajo y la atención.

¿Cuántos nits son suficientes?

Usa esto como criterio predeterminado del equipo hasta que tengas mejores datos propios:

0 nits:
  Best default. If it is not worth the author's time, skip it.

1-2 nits:
  Fine if they are clearly labeled optional and improve readability.

3+ nits:
  Stop scattering comments. Batch them in one summary, automate them,
  or open a follow-up style discussion.

Only nits remaining:
  Approve. Do not request changes.

New nits after fixes:
  Usually stop. The review is converging; do not reset the loop.

El objetivo no es prohibir el criterio. El criterio importa. Los nombres importan. La legibilidad importa.

El objetivo es hacer visible el costo.

Cada nit consume al menos cuatro cosas:

  • Atención de quien revisa.
  • Atención del autor.
  • Tiempo de CI.
  • Tiempo en la cola de merge.

A veces ese costo vale la pena. A menudo no.

Una escala sencilla de gravedad

Los equipos tienen problemas cuando todos los comentarios tienen la misma forma. Usa una escala como esta:

blocker:
  Must fix before merge.
  Examples: bug, security issue, broken test, missing required behavior.

issue:
  Probably should fix before merge, but discuss if tradeoffs exist.
  Examples: confusing design, edge case, incomplete error handling.

suggestion:
  Improvement with clear value, but not mandatory.
  Examples: simpler API, clearer helper extraction, better test name.

nit:
  Tiny polish. Optional by default.
  Examples: wording, small naming preference, minor readability tweak.

fyi:
  Knowledge transfer. No action expected in this PR.

En los comentarios de revisión, eso se traduce en:

blocker: This endpoint returns invoices by id but never checks account ownership.
That can expose one customer's invoice to another customer.

suggestion (non-blocking): This test name could describe the behavior instead
of the implementation detail.

nit: `rows` might be clearer as `invoiceRows`.

fyi: This helper has a similar shape to the one in `billing/retry.ts`.
No action needed here.

La etiqueta no es una formalidad. Es un protocolo para hacer merge.

El flujo de quien revisa

Antes de dejar un nit, sigue este pequeño árbol de decisiones:

Is this correctness, security, data loss, broken behavior, or missing tests?
  yes -> blocker or issue
  no  -> continue

Is this already covered by formatter, linter, type checker, or CI?
  yes -> do not comment manually; fix the tool
  no  -> continue

Is this a documented team convention?
  yes -> suggestion or issue, depending on impact
  no  -> continue

Will this materially help the next reader?
  yes -> nit or suggestion, clearly non-blocking
  no  -> skip it

Have you already left 2 nits?
  yes -> batch the rest or stop
  no  -> leave it as optional

El paso más difícil es el último. Quienes revisan ven muchas mejoras posibles porque son ingenieros. La decisión madura es elegir cuáles merecen el tiempo del autor en este momento.

El flujo del autor

Los autores también necesitan una política. Si tu equipo trata todos los comentarios como obligatorios, harás correcciones de más y mantendrás vivo el bucle.

Prueba esto:

For each comment:
  blocker -> fix or discuss before merge
  issue -> fix, discuss, or document the tradeoff
  suggestion -> accept if it improves the PR without expanding scope
  nit -> accept if it is trivial and you agree
  fyi -> acknowledge only if useful

Respuestas útiles para el autor:

Fixed, thanks.
Good catch. I fixed the ownership check and added a regression test.
Thanks. I am going to keep this name because it matches the API field.
Agree this could be cleaner, but I would rather handle it in a follow-up
because this PR is only wiring the migration.

No necesitas ganar cada discusión. Necesitas que el PR converja y que se atiendan los riesgos pertinentes.

Ejemplo de código: convertir los nits repetidos en una política

Si un nit se repite, ya no es un comentario de revisión. Falta automatización o una guía para el equipo.

Este pequeño ejemplo en TypeScript modela la política. No es un bot de GitHub para producción. Es una forma de hacer concreta la regla:

type Severity = "blocker" | "issue" | "suggestion" | "nit" | "fyi";

type ReviewComment = {
  body: string;
};

function classifyComment(comment: ReviewComment): Severity {
  const label = comment.body.trim().split(":")[0]?.toLowerCase();

  if (label === "blocker") return "blocker";
  if (label === "issue") return "issue";
  if (label === "suggestion") return "suggestion";
  if (label === "nit" || label === "nitpick") return "nit";
  if (label === "fyi" || label === "note") return "fyi";

  // Unlabeled comments are ambiguous, so treat them as issues until clarified.
  return "issue";
}

function reviewDecision(comments: ReviewComment[]) {
  const severities = comments.map(classifyComment);
  const nitCount = severities.filter((severity) => severity === "nit").length;

  return {
    shouldRequestChanges: severities.some(
      (severity) => severity === "blocker" || severity === "issue",
    ),
    shouldBatchNits: nitCount >= 3,
    nitCount,
  };
}

Lo importante no es la función. Es la regla:

unlabeled feedback creates ambiguity
repeated nits create noise
blockers decide mergeability
nits do not

En un equipo real, esto podría convertirse en:

  • Una guía de revisión de PR.
  • Una respuesta guardada de GitHub.
  • Una regla de Danger que advierta cuando los PR sean demasiado grandes.
  • Una regla de linter para los comentarios de estilo que se repiten.
  • Una plantilla de PR que pida a quienes revisan separar los bloqueantes de los no bloqueantes.

Qué automatizar

Automatiza todo lo que sea objetivo y se repita:

  • Formato.
  • Orden de los imports.
  • Variables no utilizadas.
  • Convenciones sencillas de nombres.
  • Comprobaciones de archivos generados.
  • Advertencias sobre el tamaño del PR.
  • Pruebas obligatorias.
  • Detección de secretos.
  • Política de dependencias.

No gastes comentarios de revisión humana en cosas que una herramienta determinista puede detectar.

Es mejor dedicar la revisión humana a preguntas como:

  • ¿Cumple esto con el requisito?
  • ¿El diseño es comprensible?
  • ¿Las pruebas son significativas?
  • ¿Se manejan los casos límite?
  • ¿Hay un riesgo de seguridad o privacidad?
  • ¿Este PR hace demasiadas cosas a la vez?
  • ¿La siguiente persona que trabaje en el código entenderá el cambio?

Esa división es el corazón de una revisión saludable:

machines:
  objective, repeated, mechanical checks

humans:
  judgment, context, design, risk, mentorship

Una política de equipo que puedes copiar

Esta es una política ligera que se adapta a la mayoría de los equipos de ingeniería:

Pull Request Review Policy

1. Label review comments:
   blocker:, issue:, suggestion:, nit:, fyi:

2. Only blocker: and issue: comments can prevent merge.

3. If the only remaining comments are nit: or fyi:, approve the PR.

4. Keep nits rare:
   - 0 is ideal
   - 1-2 is acceptable
   - 3+ should be batched or automated

5. Do not leave manual comments for formatter or linter issues.

6. If a nit appears in three PRs, convert it into:
   - a style guide rule,
   - a formatter/linter rule,
   - a snippet/template,
   - or a decision to stop caring.

7. If a review discussion goes back and forth more than twice,
   talk synchronously and summarize the decision in the PR.

Es intencionalmente aburrida. Las políticas aburridas son más fáciles de seguir.

Cuándo sí valen la pena los nits

Los nits no son malos por sí mismos. Un buen nit puede enseñar a desarrollar criterio, evitar una pequeña confusión o facilitar un cambio futuro.

Vale la pena dejar nits cuando:

  • La corrección es mínima.
  • El comentario es claramente opcional.
  • La razón es comprensible.
  • La sugerencia mejora la experiencia de la próxima persona que lea el código.
  • Quien revisa no usa el nit para bloquear la aprobación.

Ejemplo:

nit (non-blocking): `isReady` might be clearer as `hasLoadedProfile` because
this flag only tracks profile loading, not the whole page readiness.

Es útil porque explica el problema que podría encontrar una persona al leer el código en el futuro. No se limita a decir «me gusta más otro nombre».

Cuándo los nits se vuelven perjudiciales

Los nits se vuelven perjudiciales cuando:

  • Llegan sin etiqueta.
  • Bloquean la aprobación.
  • Siguen apareciendo después de cada ronda de correcciones.
  • Reflejan gustos personales en lugar de estándares del equipo.
  • Distraen de la corrección, las pruebas o la seguridad.
  • Crean un ambiente en el que el autor siente que se le dirige en función de preferencias personales.
  • Ocultan un problema mayor del proceso, como la ausencia de un formateador o una guía de estilo poco clara.

La señal de alerta no es «alguien dejó un nit». La señal de alerta es:

the PR is correct enough to merge,
but the team cannot stop discussing tiny preferences

Ese es el bucle infinito.

Los revisores de IA hacen que esto sea más importante

Las herramientas de revisión de código con IA pueden generar muchos comentarios rápidamente. Eso hace que las etiquetas de gravedad sean aún más importantes.

Un revisor de IA que deja diez comentarios opcionales sobre estilo no ayuda si acostumbra a las personas a ignorar la revisión. Un revisor de IA que separa un «posible problema de seguridad» de una «preferencia de nombres» es mucho más útil.

Para una revisión asistida por IA, usaría una regla aún más estricta:

AI may suggest nits,
but humans should not be forced to resolve them.

AI should prioritize:
  security
  correctness
  missing tests
  risky edge cases
  unclear behavior

La IA es lo suficientemente barata como para producir sugerencias interminables de pulido. La atención humana no lo es.

El mejor PR posible se puede revisar, no es perfecto

El «PR perfecto» suele ser un mito.

Es mejor un PR que se pueda revisar:

  • Tiene un propósito claro.
  • Es lo suficientemente pequeño para entenderlo.
  • Explica por qué existe el cambio.
  • Tiene pruebas donde importan.
  • Pasa las comprobaciones automatizadas.
  • Hace visibles las decisiones importantes y sus compromisos.
  • No mezcla refactorizaciones no relacionadas con cambios de comportamiento.

Ese tipo de PR les da a quienes revisan espacio para centrarse en la pregunta real:

¿Debería incorporarse este cambio al sistema?

No en:

¿Podemos seguir puliéndolo para siempre?

Vacíos pendientes en este artículo

Este artículo se basa en recomendaciones públicas de ingeniería, relatos de profesionales e investigaciones sobre el tamaño de las revisiones. El mayor vacío es que no encontré un estudio controlado sólido que aísle específicamente los comentarios de tipo nit y mida su efecto en el tiempo hasta el merge, la detección de defectos o la moral del equipo.

Investigaciones de seguimiento útiles:

  • Mide cuántos comentarios de revisión de tu equipo son blocker, issue, suggestion, nit y fyi.
  • Compara el tiempo hasta el merge de los PR con solo bloqueantes frente a los que tienen bloqueantes y muchos nits.
  • Registra con qué frecuencia se repite un nit y si debería automatizarse.
  • Prueba durante un mes una política de «aprobar con nits opcionales» y compara la percepción de los desarrolladores.
  • Evalúa las herramientas de revisión con IA por su precisión al clasificar la gravedad, no solo por la cantidad de comentarios.

Acciones de seguimiento recomendadas

Si tu equipo está atrapado en bucles de nits, empieza poco a poco:

  1. Agrega etiquetas a los comentarios durante dos semanas.
  2. Define explícitamente que nit: no es bloqueante.
  3. Aprueba los PR cuando solo queden nits.
  4. Convierte los nits repetidos en automatización.
  5. Revisa tus propios comentarios antes de enviarlos: elimina los que no cambien el resultado.

El objetivo no es bajar la calidad. Es dedicar atención de calidad a lo que importa.

Fuentes