comment-rules

Install comment policy rules for AI code editors and agents.

Ever been frustrated by code filled with more comments than actual functionality—random emojis everywhere 🚀✅❌, excessive step-by-step explanations, or distracting notes?

Meet comment-rules: a CLI tool to enforce strict comment policies for AI code editors and assistants—eliminate clutter, remove unnecessary comments, and keep only high-quality JSDoc.

What This Does

This package provides two rules:

1. jsdoc-over-inline-comments (always apply) - Prefer JSDoc over inline comments
2. manual-cleanup-comments (on-demand) - Clean up existing comments

Installation

Run directly with npx (no install required):

npx comment-rules

Or install globally:

npm install -g comment-rules

Usage

Interactive Mode (Arrow Key Navigation)

npx comment-rules

Features:

• Use Up/Down arrows to navigate
• Press Space to toggle selection
• Press A to select all, N to select none
• Press Enter to confirm

Install for Specific Editor (Project)

# Cursor (installs to current directory)
npx comment-rules cursor

# GitHub Copilot
npx comment-rules copilot

# Windsurf
npx comment-rules windsurf

# Claude Code
npx comment-rules claude

# And 30+ more editors...

Select Specific Rule

# Install only manual-cleanup-comments rule
npx comment-rules cursor --rule manual

# Install both rules
npx comment-rules cursor --rule all

Install Globally (Home Directory)

Use --global or -g flag to install rules to your home directory:

# Cursor (installs to ~/)
npx comment-rules cursor --global

# All editors globally
npx comment-rules --all -g

Install for All Editors

# Project scope (current directory)
npx comment-rules --all

# Global scope (home directory)
npx comment-rules --all --global

List Supported Editors

npx comment-rules --list

Options

Supported Editors/Agents (30+)

Manual Installation

If you prefer not to use npx, you can manually copy the rule content to your editor's config file.

CLI Agents (Single File)

These agents use a single markdown file in your project root:

Text Editors (Config Directory)

These editors use a rules directory:

Cursor:

mkdir -p .cursor/rules
curl -o .cursor/rules/jsdoc-over-inline-comments.mdc https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

Windsurf:

curl -o .windsurfrules https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

GitHub Copilot:

mkdir -p .github
curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

Cline:

curl -o .clinerules https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

Roo Code:

mkdir -p .roo/rules
curl -o .roo/rules/jsdoc-over-inline-comments.md https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

Continue:

mkdir -p .continue/rules
curl -o .continue/rules/jsdoc-over-inline-comments.md https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

Global Installation (Home Directory)

To install globally, use ~/ prefix:

# Cursor (global)
mkdir -p ~/.cursor/rules
curl -o ~/.cursor/rules/jsdoc-over-inline-comments.mdc https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

# Claude Code (global)
curl -o ~/CLAUDE.md https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc

PowerShell (Windows)

# Cursor
New-Item -ItemType Directory -Force -Path .cursor\rules
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc" -OutFile ".cursor\rules\jsdoc-over-inline-comments.mdc"

# Claude Code
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/khoidh24/comment-rules/master/jsdoc-over-inline-comments.mdc" -OutFile "CLAUDE.md"

The Rule

Absolute Rules

• DO NOT add inline or line-by-line comments
• Prefer clear naming + small functions over comments
• Write JSDoc for exported functions/classes and public methods

JSDoc Requirements

• Purpose (1 sentence)
• @param for each parameter
• @returns (or void)
• Important constraints

Good Example

/**
 * Normalizes a user-provided phone number into E.164-like format.
 * @param input - Raw phone number string from UI.
 * @param defaultCountry - ISO country code used when input has no prefix.
 * @returns Normalized string or null if invalid.
 */
export function normalizePhone(
  input: string,
  defaultCountry: string
): string | null {
  // implementation...
}

Bad Example

// get user
const user = await getUser(id);
// update user
user.name = name;
// save user
await saveUser(user);

Contributing

Pull requests welcome! If you want to add support for a new editor, edit bin/cli.js and add the editor config to the EDITORS object.

License

MIT