lint-my-lines

lint-my-lines is an ESLint plugin that provides a set of rules to enforce a clear, effective, and maintainable style for code comments.

Good comments are a crucial part of high-quality code, but they are often neglected. This project aims to help developers improve their commenting habits by providing real-time feedback within their code editor.

Features

• 24 Rules: Comprehensive coverage for comment formatting, content quality, JSDoc/TSDoc validation, accessibility, and advanced analysis.
• Multi-language Support: TypeScript, JSX/TSX, Vue, Svelte, and Markdown code blocks.
• 3+ Configuration Presets: Start quickly with minimal, recommended, strict, or language-specific presets.
• Autofix Support: Many rules automatically fix issues for you.
• Style Guide: Based on a comprehensive STYLE_GUIDE.md that explains the rationale behind each rule.
• Extensible: Built as an ESLint plugin, making it easy to integrate into existing JavaScript and TypeScript projects.

Getting Started

Option 1: Standalone Binary (No Node.js Required)

Download the pre-built binary for your platform from GitHub Releases:

# Make executable (macOS/Linux)
chmod +x lint-my-lines-macos-arm64

# Lint current directory
./lint-my-lines lint

# Lint specific files
./lint-my-lines lint src/**/*.js

# Use strict preset
./lint-my-lines lint --preset strict

# Auto-fix issues
./lint-my-lines lint --fix

# Output as JSON
./lint-my-lines lint --format json

Option 2: npm Installation

npm install eslint-plugin-lint-my-lines --save-dev

Quick Setup with CLI

The fastest way to configure lint-my-lines:

# Generate ESLint config with recommended preset
npx lint-my-lines init

# Use a different preset
npx lint-my-lines init --preset strict

# For ESLint v8 (legacy config)
npx lint-my-lines init --no-flat

ESLint Flat Config (v9+)

// eslint.config.js
import lintMyLines from "eslint-plugin-lint-my-lines";

export default [
  lintMyLines.configs["flat/recommended"],
];

Legacy Config (ESLint v8)

// .eslintrc.js
module.exports = {
  extends: ["plugin:lint-my-lines/recommended"]
};

Available Presets

Manual Configuration

You can also configure individual rules:

{
  "plugins": ["lint-my-lines"],
  "rules": {
    "lint-my-lines/enforce-todo-format": "warn",
    "lint-my-lines/no-commented-code": "error",
    "lint-my-lines/enforce-capitalization": "warn"
  }
}

Extending Presets

Start with a preset and customize as needed:

// .eslintrc.js
module.exports = {
  extends: ["plugin:lint-my-lines/recommended"],
  rules: {
    // Override specific rules
    "lint-my-lines/enforce-comment-length": ["error", { maxLength: 80 }],
    // Disable a rule from the preset
    "lint-my-lines/ban-specific-words": "off"
  }
};

Rules

Comment Format Rules

Content Quality Rules

JSDoc/TSDoc Rules

Template Rules

Advanced Analysis Rules

Accessibility Rules

See the Accessibility Guide for best practices on documenting accessibility in your codebase.

Preset Details

Minimal

{
  "lint-my-lines/enforce-todo-format": "warn",
  "lint-my-lines/enforce-fixme-format": "warn",
  "lint-my-lines/enforce-note-format": "warn",
  "lint-my-lines/no-commented-code": "warn"
}

Recommended

Includes everything in minimal, plus:

{
  "lint-my-lines/enforce-comment-length": ["warn", { maxLength: 120 }],
  "lint-my-lines/enforce-capitalization": "warn",
  "lint-my-lines/comment-spacing": "warn",
  "lint-my-lines/ban-specific-words": ["warn", { includeDefaults: true }]
}

Strict

Includes everything in recommended (as errors), plus:

{
  "lint-my-lines/no-obvious-comments": ["warn", { sensitivity: "medium" }],
  "lint-my-lines/require-explanation-comments": ["warn", { requireFor: ["regex", "bitwise"] }],
  "lint-my-lines/require-jsdoc": "warn",
  "lint-my-lines/valid-jsdoc": "warn",
  "lint-my-lines/jsdoc-type-syntax": ["warn", { prefer: "typescript" }],
  "lint-my-lines/require-file-header": ["warn", { requiredTags: ["@file"] }]
}

Analysis

Advanced analysis rules for code quality insights:

{
  "lint-my-lines/stale-comment-detection": "warn",
  "lint-my-lines/todo-aging-warnings": ["warn", { maxAgeDays: 30 }],
  "lint-my-lines/comment-code-ratio": ["warn", { minRatio: 0.05, maxRatio: 0.40 }]
  // issue-tracker-integration requires configuration
}

Note: issue-tracker-integration requires explicit configuration for your tracker. See issue-tracker-integration docs.

Integration

Pre-commit Hooks

With Husky and lint-staged:

{
  "lint-staged": {
    "*.{js,ts}": "eslint --fix"
  }
}

GitHub Actions

Copy the workflow from .github/workflows/lint-comments.yml or create your own:

- run: npm ci
- run: npx eslint .

See the full Integration Guide for CI/CD, editor setup, and monorepo configurations. Check the FAQ for common questions and troubleshooting tips.

Language Support

lint-my-lines supports multiple languages and frameworks:

Example: Multi-language Project

// eslint.config.js
import lintMyLines from "eslint-plugin-lint-my-lines";

export default [
  lintMyLines.configs["flat/recommended"],
  lintMyLines.configs["flat/typescript"],
  lintMyLines.configs["flat/vue"],
];

See the Integration Guide for detailed setup instructions.

License

This project is licensed under the MIT License. See the LICENSE file for details.