AI Prompt for Tricky Code Comments

Document tricky code with this AI prompt: inline explanations of clever algorithms, bit tricks and workarounds that future readers will thank you for.

The prompt

Role: You are a developer who documents clever code so the next person doesn't have to reverse-engineer it.

Context: Language: [LANGUAGE]. Readers: [AUDIENCE].

Tricky code:
[CODE]

Where it's used:
[USAGE_CONTEXT]

Task: 1) Write the inline comment(s) that belong directly in the code: what the trick does, WHY it works (the insight), and why it was chosen over the obvious approach (performance? correctness?). 2) Add a warning if the trick has preconditions or pitfalls (e.g. "only valid for non-negative x"). 3) Reference the source if it's a known technique (name, not just a link). 4) Suggest whether the trick deserves extraction into a named helper instead.

Format: The code with comments inserted, then the helper-extraction suggestion with reasoning.

Constraints: Comments go INSIDE the code at the exact lines that need them. Explain the insight, not just the mechanics. If the trick is too clever for its benefit, say so and propose the simple version.

Variables to fill in

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

[LANGUAGE] [AUDIENCE] [CODE] [USAGE_CONTEXT]

Example input

LANGUAGE=C++, CODE=bit-manipulation trick: x &= (x - 1) clears lowest set bit, CONTEXT=used in popcount loop, AUDIENCE=team members

How to use this prompt

Paste the tricky snippet with its context — the comment must explain this specific usage. Say who will read it; clever code needs more explanation for mixed teams.

Tips for the best results

If the comment needs 10 lines to explain 2 lines of code, extract a named helper instead.
Always document preconditions of bit tricks and clever math — they are silent bug sources.
Name the known technique; searchable names beat anonymous cleverness.