Documenting Code with AI: Comments and READMEs People Actually Read
Most code documentation fails in the same way: it describes what the code does, which anyone can already see, and skips why it does it that way, which is the one thing a future reader cannot work out. AI assistants are good at generating the first kind of documentation in bulk, which is exactly why they need a human in charge. Used well, they take the tedious drafting off your plate and leave you free to add the judgement — the reasons, the trade-offs, the warnings — that make documentation worth reading.
1. Document the why, not the what
A comment that says "loop through users" above a loop through users adds nothing. A comment that says "we process users in batches of 100 because the payment API rejects larger requests" saves the next developer from rediscovering that limit the hard way. When you ask an AI tool to draft documentation, tell it explicitly to explain reasons, constraints and non-obvious decisions, and to skip restating anything the code already says plainly. Then read the draft and delete every sentence that merely repeats the code.
2. Give the AI the context it cannot see
An AI assistant only knows what you show it. Fed a single function in isolation, it will invent plausible-sounding reasons for design choices it cannot see — a confident explanation of a decision that was actually made for a reason elsewhere in the codebase, or for no reason at all. Before asking for documentation, include the surrounding context: the function that calls this one, the configuration it depends on, the ticket or requirement behind it, and any quirk of the system it works around.
The same discipline applies elsewhere in coding: our guide to debugging with an AI assistant makes the same point. Vague input produces fluent guesswork, and fluent guesswork in documentation is worse than none, because people trust it.
3. Keep comments short and close to the code
A comment is most useful when it sits right where the confusion will happen, and least useful when it lives in a separate document nobody opens. Put short explanations above tricky logic, at the top of files with unusual setup, and wherever a future reader might reasonably think "this looks wrong" — because that is usually where the original author made a deliberate choice. One or two lines is enough in most cases; if you need a paragraph, consider whether a better name for the function or variable would do the job instead.
4. Write a README that gets someone running in ten minutes
A project README has one primary audience: a person who has just arrived and wants to run the thing. Everything else is secondary. The best READMEs answer, in order: what this project does, what you need installed, the exact commands to get it running, how to run the tests, and where to ask for help. If a new contributor cannot reach a working setup by following the README alone, the README has failed, no matter how thorough its architecture section is.
AI assistants are genuinely helpful here, because they turn messy setup notes into a clean, ordered document. Give the tool your actual steps — the real commands, prerequisites and first-time errors — and ask it to organise them. Then follow the README yourself from scratch and fix every step where it breaks. That one test catches more errors than any amount of proofreading.
5. Treat generated documentation as a draft, always
Never merge AI-written documentation without reading it as critically as you would read code. Models hallucinate parameters that do not exist, describe behaviour from an older version of the function, and confidently document edge cases the code never handles. A wrong comment is worse than a missing one, because a missing comment makes a reader look at the code, while a wrong comment sends them confidently in the wrong direction.
Build a simple habit: after generating documentation, verify every factual claim against the code — parameter names, return values, error conditions, limits. This mirrors the review discipline in our guide to reviewing code securely with AI: the assistant accelerates the work, but you remain responsible for what ships. If you are learning a new language at the same time, our guide to learning a new language with AI help shows how to use the assistant as a tutor rather than an authority.
6. Keep documentation alive when code changes
Documentation rots faster than code, because code breaks visibly when it is wrong and documentation does not. The most effective defence is to keep documentation small: fewer words mean fewer words to go stale. The second defence is habit — whenever you change behaviour, update the comment or README section in the same change, not in a separate "documentation later" task that never happens. If you use an AI assistant, asking it to update the existing documentation alongside a code change is often faster than writing the update from scratch, and it keeps the two in step.
7. Let prompts do the boring consistency work
If your team writes in different styles, an AI assistant can enforce consistency cheaply. Save a short prompt stating your house style — comment length, tone, what to include and leave out — and reuse it for every request, so the output reads like one author wrote it. Our guide to prompt engineering basics explains how to write instructions that give steady, repeatable results.
Bottom line: Let AI draft the documentation, but you supply the why, verify every claim against the code, and keep it short enough that the next person actually reads it.