eslint-plugin-clean-comments

Un plugin ESLint para mantener los comentarios que suman y eliminar el ruido.

Reglas

clean-comments/no-decorative-header

Detecta separadores decorativos que no aportan información:

// ✗ Mal — ruido visual
// ── Config ──
// ═══════════════════
// --- Section ---

// ✓ Bien — el código ya comunica la estructura
export { configureSDUI } from './config';

Auto-fix: --fix los elimina automáticamente.

clean-comments/no-redundant-jsdoc

Detecta JSDoc que solo repite el nombre de la función:

// ✗ Mal — el nombre ya dice lo que hace
/** useScreen — fetches a full ScreenResponse */
export function useScreen(route) {}

// ✓ Bien — explica POR QUÉ, no qué
/**
 * Retry with exponential backoff because the upstream API is flaky.
 */
function fetchWithRetry(url) {}

Auto-fix: No tiene. Requiere decisión manual porque a veces el JSDoc aporta contexto no obvio. Si el equipo decide que es redundante, se borra a mano.

Instalación

npm install --save-dev eslint-plugin-clean-comments

Uso

Configuración mínima (recommended)

Agregar al .eslintrc.cjs:

module.exports = {
  plugins: ['clean-comments'],
  rules: {
    'clean-comments/no-decorative-header': 'warn',
    'clean-comments/no-redundant-jsdoc': 'warn',
  },
};

Configuración strict (rompe el build)

module.exports = {
  plugins: ['clean-comments'],
  rules: {
    'clean-comments/no-decorative-header': 'error',
    'clean-comments/no-redundant-jsdoc': 'error',
  },
};

Con preset recomendado

module.exports = {
  extends: ['plugin:clean-comments/recommended'],
};

Con preset strict

module.exports = {
  extends: ['plugin:clean-comments/strict'],
};

TypeScript + NestJS

module.exports = {
  plugins: ['clean-comments', '@typescript-eslint'],
  rules: {
    'clean-comments/no-decorative-header': 'warn',
    'clean-comments/no-redundant-jsdoc': 'warn',
  },
  overrides: [
    {
      files: ['**/*.{ts,tsx}'],
      parser: '@typescript-eslint/parser',
    },
  ],
};

Uso con --fix

# Ver warnings
npm run lint

# Auto-fix (remueve headers decorativos automáticamente)
npm run lint -- --fix

Integración en CI

Agregar al pipeline:

- run: npm run lint

Si se usa en modo warn, el CI no falla pero deja visibilidad. Para hacerlo estricto en CI:

- run: npm run lint -- --max-warnings 10

Política de comentarios

El criterio detrás de estas reglas:

| Tipo | Debe tener comentario | Ejemplo | |------|----------------------|---------| | TODO | ✅ Siempre | // TODO: paginar cuando haya > 100 items | | Workaround | ✅ Siempre | // HACK: this works around a race condition in SDK v3 | | Por qué no obvio | ✅ Siempre | // Inject formKey from block.key so TextInput can report its value | | Qué hace el código | ❌ Nunca | El nombre de la función y el código ya lo dicen | | Separadores decorativos | ❌ Nunca | // ── Config ── | | JSDoc que repite el nombre | ❌ Nunca | /** useScreen — fetches... */ |

Desarrollo local

# Correr tests
node tests/no-decorative-header.test.js
node tests/no-redundant-jsdoc.test.js

# Probar contra el proyecto local
npm link  # en packages/eslint-plugin-clean-comments/
npm link eslint-plugin-clean-comments  # en el proyecto destino

Licencia

MIT