AI Prompt for Comment Quality Review

Audit code comments with this AI prompt: find stale, noisy and missing comments against your standard, then get a cleaned-up version back plus team habits.

The prompt

Role: You are a documentation reviewer who holds comments to a high bar.

Context: Language: [LANGUAGE]. Our comment standard: [STANDARD, e.g. why-not-what, max 2 lines, TODOs must have owners].

Commented code:
[CODE]

Task: 1) Audit every comment against [STANDARD]: flag stale comments (contradict the code), noise comments (restate the obvious), missing comments (tricky code unexplained), and misleading comments (worse than none). 2) Rate the file's comment health 1-10. 3) Provide the cleaned-up code: stale/noise removed, missing added, misleading corrected. 4) Give 3 comment habits for the team based on the patterns you saw.

Format: Findings grouped by category with line refs, then the score, then cleaned code, then the 3 habits.

Ask the AI to produce a before-and-after readability score for the file, so the team sees the audit's value in a number. Visible progress sustains documentation discipline.

Constraints: Be strict — a misleading comment is a bug. Do not just delete; replace noise with value or nothing. Keep the team's voice in the rewritten comments.

Variables to fill in

Replace each [variable] in the prompt with your own details:

[LANGUAGE] [STANDARD] [CODE]

Example input

LANGUAGE=JavaScript, CODE=recently commented module, STANDARD=why-not-what, max 2 lines per comment, ISSUES=stale comments after refactor

How to use this prompt

Give it your comment standard — the audit measures against it. Mention the specific problem you suspect (staleness, noise) so it looks there first.

Tips for the best results

Run this after big refactors — that is when comments go stale fastest.
Turn the 3 habits into your team's contributing guide.
Ask it to check TODO/FIXME comments for owners and dates.

Frequently asked questions

Can it detect stale comments?

It audits against your standard and flags stale, noisy, and missing comments — then shows the corrected version.

What is the worst kind of comment?

A misleading one — it actively teaches the wrong thing. The prompt treats those as bugs, not style issues, and rewrites them first.

Related SlickCalcs tools

Scientific Calculator

More coding prompts

AI Prompt for SQL-to-ORM Conversion

Convert raw SQL to ORM code with this AI prompt: idiomatic queries for your ORM, N+1 risks flagged, and guidance on what should stay raw SQL.

AI Prompt for Storage Decisions

Decide where data lives with this AI prompt: database vs cache vs memory analysis on durability, latency, size, and operational cost trade-offs.

AI Prompt for Structure Trade-offs

Compare data structures head-to-head with this AI prompt: trade-off matrix on your workload, cache and memory analysis, and a conditional winner.

AI Prompt for Sync-to-Async Conversion

Convert sync code to async with this AI prompt: correct async/await conversion, independent calls parallelized, and every semantic change flagged.

AI Prompt for Git Commit Messages

Write perfect git commit messages with this AI prompt: conventional-commit format from your diff, with the why explained and scope chosen correctly.

AI Prompt for REST-to-GraphQL

Convert REST to GraphQL with this AI prompt: client-driven schema design, N+1-safe resolvers with batching, and a reversible strangler migration plan.