AI Prompts for Code Documentation

Before: The Weak Prompt

Picture this: you're a backend developer at a SaaS company. The sprint ended an hour ago, your Jira tickets are closed, and your tech lead just Slacked you: "Hey, can you document the new payment module before EOD?"

You open the AI, paste your code, and type the first thing that comes to mind:

Write documentation for this code.

class PaymentProcessor:
    def __init__(self, gateway, retry_limit=3):
        self.gateway = gateway
        self.retry_limit = retry_limit

    def charge(self, amount, card_token, idempotency_key):
        for attempt in range(self.retry_limit):
            result = self.gateway.charge(amount, card_token, idempotency_key)
            if result.success:
                return result
        raise PaymentFailedException("All retry attempts exhausted")

The AI gives you something. A docstring. A generic description. "This class processes payments." You paste it in, commit, done.

Three weeks later, a new developer joins. They look at the docs and still have five questions — because the documentation described what, not why.

Why It Fails

"Write documentation for this code" is arguably the most common documentation prompt and one of the least effective. Here's what goes wrong:

No audience specification. Docs for a junior dev look different from docs for an API consumer who never sees the implementation. The AI doesn't know who's reading.

No documentation type. Inline comments, docstrings, README sections, API reference docs, and architectural decision records all serve different purposes. Without guidance, the AI defaults to the most generic form.

No coverage requirements. The prompt says nothing about edge cases, error behavior, retry logic, or the idempotency key — which is actually the most important parameter to document in a payment context.

⚠️ Common mistake: Treating documentation as an afterthought prompt. The weaker your prompt, the more your future self (or your teammates) will pay for it in debugging time.

After: The Improved Prompt

You are a technical writer creating documentation for a Python payment processing module.

Audience: Mid-level developers who will use this class via internal SDK — they understand Python but may not know our payment gateway specifics.

Write the following:
1. A Google-style docstring for the PaymentProcessor class (include class-level description, Attributes section)
2. A Google-style docstring for the `charge` method (include Args with types and descriptions, Returns, Raises, and a usage Example)
3. Two inline comments inside charge(): one explaining why idempotency_key matters, one explaining the retry strategy

Code:
class PaymentProcessor:
    def __init__(self, gateway, retry_limit=3):
        self.gateway = gateway
        self.retry_limit = retry_limit

    def charge(self, amount, card_token, idempotency_key):
        for attempt in range(self.retry_limit):
            result = self.gateway.charge(amount, card_token, idempotency_key)
            if result.success:
                return result
        raise PaymentFailedException("All retry attempts exhausted")

Important: Document the *why* behind the retry logic and idempotency key — not just what they are.

What this does: It specifies the audience, the documentation format, the exact deliverables, and explicitly asks for the reasoning behind design decisions — which is what documentation is actually for.

⚡ Pro tip: Add "Document the why, not just the what" to every documentation prompt. It's a one-line instruction that reliably produces docs that answer the follow-up questions before they're asked.

Breaking Down Each Element

"You are a technical writer" — role-setting shifts the AI's output register. It writes with more structure and less code-explanation padding.

Audience specification — this one change probably has the biggest impact. "Mid-level developers using an SDK" implies they don't need basic Python explained, but they do need gateway-specific context.

Numbered deliverables — asking for three specific things prevents the AI from deciding what to document. You control coverage.

"Google-style docstring" — naming a documentation standard (Google, NumPy, Sphinx, JSDoc) gives the AI a formatting contract to follow. Without it, you get whatever format the AI was trained on most recently.

"Document the why" — this is the instruction most developers skip. It's also the one that turns okay docs into good docs.

⚡ Pro tip: If you're documenting a public API, add: "Assume the reader has never seen the underlying implementation." This forces the AI to explain parameters without assuming shared context — the way a real API consumer reads docs.

Variations for Different Contexts

For JavaScript with JSDoc:

Write JSDoc comments for this function. Include @param with types, @returns, @throws, and one @example showing a real-world usage. Audience: developers consuming this as part of a public npm package.

What this does: Produces JSDoc-compatible output ready for tools like TypeDoc, with an example that helps consumers copy-paste.

For README-level documentation:

Write a README section for the PaymentProcessor class. Include: a 2-sentence overview, a quick-start code example, a table of constructor parameters with types/defaults/descriptions, and a "Common Errors" subsection covering PaymentFailedException.

What this does: Structures README content for scannability — most devs read tables and code blocks first, prose second.

For architectural decision records (ADR):

Write an ADR explaining the decision to implement retry logic with a configurable limit rather than exponential backoff. Cover: Context, Decision, Consequences (positive and negative).

What this does: Captures institutional knowledge that code comments can't — the trade-off reasoning behind a design choice.

⚡ Pro tip: Build a documentation prompt template for each type your team uses. Store them in a shared prompt library. PromptABCD works well for this — it keeps your vetted prompts accessible across the team without living in a forgotten Notion page.

Save and Reuse This

The improved prompt above is a template. Before reusing it, swap out three things: the programming language and doc style, the audience description, and the specific design decisions worth explaining.

One rarely-discussed benefit of better ai prompts code documentation is what it reveals about your code's design. If you can't write a clear one-sentence description of what a function does, that's often a sign the function does too many things. The documentation process becomes a design smell detector — and AI-assisted documentation makes that feedback loop faster.

Actually, the hardest part of ai prompts code documentation isn't the prompt — it's the habit. Pair your PR template with a documentation step. When you open a PR, run the prompt on any new public-facing class or function. Fifteen minutes of prompting saves two hours of onboarding questions. And if you track it over a quarter, you'll notice a secondary benefit: your documentation is more consistent across the codebase. When everyone uses the same prompt template and the same doc standard, new developers can navigate the entire codebase with the same mental model — not six different documentation styles from six different developers. That consistency compounds quietly over months and dramatically reduces the time it takes to onboard the next hire.

Documentation for Legacy Code

Legacy codebases present a unique documentation challenge: you often don't know why the original developer made certain choices. The AI can help reconstruct the likely reasoning, even without access to the author.

This function exists in a codebase from 2017. Based on what it does, write a documentation comment that explains:
1. What this function does
2. The most likely reason it was written this way rather than a simpler approach
3. Any warnings a developer modifying this code should know

Note any places where the current behavior looks unintentional versus deliberate.

Code: [paste legacy code]

What this does: Gets you a hypothesis-driven documentation pass that flags both the function's purpose and its potential landmines. It's not perfect — the AI may be wrong about intent — but it's a starting point that saves an hour of archaeology.

⚡ Pro tip: After documenting legacy code with AI, always add "Documented by AI based on behavior analysis — verify intent with original author or git history" to the doc comment. Future maintainers deserve to know the provenance of the documentation they're trusting.

Keeping Documentation in Sync with Code

One problem even good documentation prompts don't solve automatically: docs going stale. A function's behavior changes in a refactor, but the docstring stays frozen in the old version. Stale documentation is arguably worse than no documentation — it actively misleads.

Use a sync-check prompt after any significant refactor:

Here is a function and its existing documentation. Identify any places where the documentation no longer accurately describes the current code. For each mismatch, write the corrected documentation.

Current code: [paste]
Existing documentation: [paste]

What this does: Surfaces documentation debt immediately after the code changes — when the developer still has full context — rather than leaving it for the next person to stumble over six months later.

For teams with larger codebases, this sync-check is worth running as part of your PR template. Add "run documentation sync check on any function with existing docs that you've modified" as a checklist item. It takes two minutes and prevents the creeping documentation drift that makes large codebases progressively harder to navigate.

⚡ Pro tip: When a function's documentation is longer than the function itself, that's a signal to split the function. Documentation length is a surprisingly good proxy for function complexity — and AI-generated docs make this signal visible in a way that hand-written minimal comments don't.

Documentation quality is ultimately a team culture issue as much as a tooling one. The best prompt in the world only helps if developers run it. Pairing good prompts with a lightweight process — a PR checklist item, a weekly documentation review — is what turns occasional good docs into a consistent standard. Start with the highest-traffic code paths and work outward from there.