Prompt Workshop
Why it is written this way
Tap a block to see its paragraph
You are a software engineer who frequently takes over other developers' code. Your standard for writing comments is: "What does someone opening this code for the first time six months from now need to know?"
The code below is written in {{target language}}, and the comments should follow the {{annotation format style}} standard.
Please read the code and add comments. Do not change a single character of the original code; return the entire original code exactly as is, with only the comments inserted.
In the comments, explain what cannot be inferred just by reading the code, rather than stating what the code already says. For example, instead of writing "Calculates discount amount" on the discount calculation line, write why that value exists, such as "Coupon discount cannot exceed 30% of the total payment (business policy ceiling)". In the function docstring, specify what parameters it takes, what it returns, and how it handles edge cases or exceptions.
Do not comment on every single line. Only add comments where key decisions are made, exceptions are handled, or where future modifications could be risky. If there are parts where the business intent cannot be determined from the code and requires guesswork, do not guess in the comments; list them separately at the very end under a "Needs Verification" section.
Code: """ {{source code snippet}} """
- Role Who answers ×1
- Material What the AI needs to know ×3
- Work What to do, and how ×1
- Output What comes back, in what shape ×1
When you ask an AI to write code comments, it often adds a comment on almost every line—such as putting "Calculate total sum" right above total = sum(...). While not technically wrong, it merely repeats the code in natural language, bloating the file while critical context like why the discount is capped at 30% remains missing. This prompt establishes explicit criteria for where comments belong rather than just what they contain.
Read the full explanation · 3 paragraphs
Embedding direct examples within the prompt is the key mechanism. A vague instruction like "Please add meaningful comments" specifies nothing and yields generic results. Showing a bad comment alongside a good comment gives the AI a clear baseline, which it then applies with consistent depth across the entire snippet.
Constraints are applied in two crucial directions. Without the rule "Do not change a single character of the original code", the AI might rename variables or refactor conditional blocks while adding comments. When code modifications are mixed into comment reviews, verifying changes becomes difficult. "Do not comment on every single line" prevents excessive noise, and the "Needs Verification" section gives the AI a safe place to surface uncertainties instead of pretending to understand them.
Specifying the comment format by name is also essential. When generating docstrings repeatedly, some functions might receive full parameter tables while others get single-line summaries; explicitly naming the convention keeps the entire file uniform. Wrapping the code in """ ensures that existing comments inside the snippet are not misinterpreted as prompt instructions.
Unfamiliar terms? See Aha AI: few-shot, output-format
Compared with a bad example
Add some comments to this code.
(paste code)
Comments are added to almost every line. Most simply translate the code into plain words, making the actual logic harder to read. Additionally, variable names or indentations may quietly change, leading to accidental commits without knowing what actually changed.
Variations
When existing comments contradict the code
Outdated comments are more dangerous than no comments. Instructing the AI to compare rather than rewrite prevents it from overwriting accurate, useful comments.
Show prompt
The {{target language}} code below already contains comments. Compare the code with the comments and identify only the comments that no longer match the current implementation. Organize the findings in a table with the columns: "Location | What the Comment Says | What the Code Actually Does | Corrected Comment". Do not include accurate comments in the table.
""" {{source code snippet}} """
Adding an onboarding header summary
Use this when you need file-level documentation rather than individual function docstrings. Setting a line limit prevents the summary from becoming a redundant line-by-line recap.
Show prompt
Write a top-of-file summary in {{annotation format style}} for someone taking over the {{target language}} code below. Structure it in this order: what this file is responsible for, what assumptions or prerequisites it relies on, and what related components must be reviewed when modifying it. Keep the total length under 10 lines.
""" {{source code snippet}} """
Model notes
Passing an entire large file at once often results in shorter comments toward the bottom functions. Split your code into chunks of 5 to 6 functions and include the format specification each time.
When asking the AI to output the entire codebase with comments, long files may get truncated or replaced with placeholders like "...rest of code". In such cases, process the code in batches of 5 to 6 functions, or ask only for a table of "comment text and target line numbers" to paste into your editor manually.
Last updated 2026-09-02 · Found a mistake? Let us know