If you've ever opened a file, stared at a function name like processData or handleResponse, and spent the next ten minutes tracing call stacks just to figure out what it does — this is for you. Claude Code can scan your functions, read the actual logic, and attach meaningful comments in the time it takes to make coffee. This tutorial walks through the exact commands, format options, and self-verification steps that make AI-assisted documentation practical for daily use.
1. Why This Matters Now
Most developers write comments with good intentions and terrible follow-through. Under deadline pressure, the comment either doesn't get written or ends up as // does the thing. The result is a codebase where every onboarding session turns into an archaeology project.
The real pain isn't laziness — it's that writing accurate comments costs cognitive effort. You have to context-switch from building to explaining, and explanation requires you to hold the full mental model of a function in your head while also translating it into prose. That's expensive. It compounds every time a new teammate joins or you return to a module after three months away.
AI comment generation flips the cost structure. Instead of you summarizing code into language, the model reads the logic and produces the summary. Your job becomes reviewing a draft instead of writing from scratch — a much lighter lift.
2. The Core Idea
One Claude Code command on a file produces complete, context-aware doc comments for every function — faster than you can manually write one.
The key difference from naive comment generation is that Claude doesn't just echo the function signature back at you. It reads the actual logic: what branches exist, what the return value represents, what could throw an error. A function that pulls price and volume out of an exchange API response gets a comment that says exactly that — not // processes data.
The table below shows what you typically get without this approach versus what Claude produces:
| Situation | Manual (rushed) | Claude Code output |
|---|---|---|
| Parameter description | value — a value |
rawTick — exchange API tick object containing bid, ask, and last price |
| Return description | returns result |
Returns normalized trade object with ISO timestamp and decimal quantity |
| Error condition | (missing) | Throws RangeError if quantity is zero or negative |
| Time to document 100-line file | 15–30 min | ~12 seconds |
The speed comes from the model processing the entire file in one pass. You get consistent style, consistent depth, and no functions accidentally left bare because you ran out of time.
3. How to Implement It
Basic JSDoc on a JavaScript utility file
Open your terminal in the project root and run:
claude "Add JSDoc comments to every function in utils/parser.js. Include parameter types, descriptions, and return value."
Claude reads the file, identifies every exported and internal function, traces each one's logic, and writes the doc block inline. You don't need to specify the file format — it detects .js and defaults to JSDoc syntax.
Verification:
git diff utils/parser.js
Expected output: every function preceded by a /** ... */ block with @param and @returns tags, no functions skipped. If a function had no return value, Claude writes @returns {void} rather than omitting the tag.
Google-style docstrings for Python
claude "Add Google-style docstrings to the public functions in trade_calculator.py. Include Args, Returns, and Raises sections."
Input function (before):
def calculate_slippage(order_price, market_price, quantity):
spread = abs(order_price - market_price)
return (spread / market_price) * quantity
Output (after Claude):
def calculate_slippage(order_price, market_price, quantity):
"""Calculate expected slippage cost for a given order.
Args:
order_price (float): Limit price specified in the order.
market_price (float): Current mid-market price at execution time.
quantity (float): Order size in base currency units.
Returns:
float: Estimated slippage in base currency, always non-negative.
"""
spread = abs(order_price - market_price)
return (spread / market_price) * quantity
NumPy style (for scientific or data-heavy code)
claude "Add NumPy-style docstrings to every function in signal_processor.py. Include Parameters, Returns, and Notes sections."
reStructuredText (for Sphinx-based projects)
claude "Add reST-format docstrings to auth/validators.py. Use :param:, :type:, :returns:, and :raises: directives."
Switch the format string to match your team's convention — the rest of the command stays identical.
Self-verification pass
After adding comments, run a second command in the same session:
claude "Review the comments you just added. List any descriptions that don't match the actual function logic, or that are vague enough to be misleading."
This catches the edge cases: a function that was refactored recently but whose name still reflects the old behavior, or a parameter whose type changed from int to float without a rename. Claude cross-references the comment it just wrote against the code and flags mismatches as a numbered list you can address immediately.
4. What to Watch in Production
Generated comments can lag behind refactors. If you add comments today and rewrite the function next week, the comment becomes a liability. Treat AI-generated docs the same way you treat any other code: they require maintenance. Consider adding a lint step with eslint-plugin-jsdoc (JS) or pydocstyle (Python) to your CI pipeline so outdated or malformed docs surface as warnings.
Private functions and internal helpers. By default Claude documents everything it finds. If your team convention is to skip _private methods or unexported internals, add that constraint explicitly:
claude "Add JSDoc to all exported functions in api/client.js. Skip private methods prefixed with underscore."
Large files take longer, but not much longer. In practice, a 100-line utility file completes in roughly 12 seconds on a standard machine. A 400-line module takes 30–45 seconds. Files above ~600 lines are better split into separate commands per logical section to keep the output reviewable — you don't want to review 80 doc blocks in one git diff.
Environment differences. These commands work identically on macOS, Linux, and Windows (WSL). If you're running Claude Code inside a Docker container with a read-only filesystem, mount the source directory with write permissions before running — the tool edits files in place.
Don't skip the git diff review. AI-generated content is almost always correct for straightforward functions. It gets shakier on functions with implicit side effects or that depend on global mutable state. Reading the diff before committing takes 60 seconds and catches the 5% of comments that need a manual tweak.
FAQ
When is the right time to run this on a file?
The highest-value moment is just before a code review or before merging a feature branch. You've written the logic, it works, and now you're switching from builder to communicator — that's when adding comments is natural, and Claude can do the mechanical part instantly. It's also worth running on any legacy file you're about to touch, so you're not documenting from memory but from the live code.
What should I check before running this on a production codebase?
Two things: confirm Claude Code has write access to the files you're targeting, and run the command on one file first rather than a whole directory. Check the diff carefully on that first file. If the output quality looks right for your codebase's style, you can broaden the scope. Also verify your team has agreed on a doc format — adding JSDoc to a project that uses reST, or vice versa, creates inconsistency that's harder to fix than no docs at all.
What's the easiest way to verify the output is accurate?
The two-step approach in this tutorial covers it: git diff to see what changed, then the follow-up Claude command to check for logic mismatches. For JavaScript projects, npx jsdoc --dry-run utils/parser.js will validate that the generated JSDoc parses without errors. For Python, python -m pydoc trade_calculator renders the docstrings as human-readable text — if something looks wrong in that output, it'll be obvious.
Closing
The comments you skip today become the questions you answer in Slack three months from now. Running claude "add JSDoc to utils/parser.js" on the file you're already looking at costs you nothing and pays out every time someone — including future you — opens that file.
Next step: pick one file in your current project that you've been meaning to document and run the command before closing your editor today.
🐦 Faster updates on X: @baegseungh7061
📚 More in this series: Code Intro
💌 Subscribe: Follow on X or grab the RSS
댓글
댓글 쓰기