What is a code comment — and why AI writes them wrong

Open any code AI has written for you. Odds are you'll find something like this:
// increase the counter by 1
count = count + 1
There's a comment. The value is zero. It retells what's already visible in the line below. And the thing that would actually help a month from now isn't there. Let's figure out what a comment is and what it should look like.
What a comment is
A comment is text in code that the program skips completely. It's for people, not the computer. A note in the margin.
Every language has its own symbol that starts a comment:
// JavaScript, TypeScript, Swift, Kotlin — one line
/* several lines
work too */
# Python, Ruby, Bash — a hash
<!-- HTML — like this -->
The program doesn't read anything after the symbol. You can write whatever you like there — in any language, even poetry. It won't affect how the code runs.
What to put in a comment: "why", not "what"
Here's the main idea of this article. Code answers "what's happening" on its own — you can read it. But it will never answer "why like this".
Compare:
// wait 300 ms
await sleep(300)
// the payment server rejects more than 3 requests per second — hence the pause
await sleep(300)
The first comment is useless. The second one saves you. Without it, a month later you (or AI) will see an "extra" pause, delete it for speed — and payments will start failing.
A good comment explains what's not in the code:
- the reason behind an odd decision — "like this because…";
- a trap — "don't change the order, or else…";
- a link to the source — a ticket, docs, a bug;
- a temporary patch — "remove once the server is fixed".
Why comments lie
Here's the unpleasant part. The computer checks code: break it and you see it right away. Nobody checks comments.
So they go stale. Someone fixes the code and forgets the note above it. Now it confidently describes something that no longer exists. A stale comment is worse than none: it misleads both you and AI.
Hence two rules:
- Fewer comments, fewer lies. If a good variable name can make the code clear, do that instead.
pauseForPaymentLimit()is clearer thansleep(300)with a comment. - Changing code? Check the note above it. It takes one second.
A separate word on commented-out code. Lines "switched off just in case" clutter the project. Delete them without fear: git remembers the whole history, and you can always bring the old version back.
How to steer AI with comments
This is where comments become a superpower. For AI they aren't just notes — they're instructions.
A comment as an order. Write what you need in an empty spot in the file — and your editor's autocomplete will write the code to match:
// function: takes a list of orders, returns the total of paid ones only
A comment as a fence. An AI agent reads a file before editing it. A warning right in the code works better than a request in chat that it will forget:
// IMPORTANT: don't change the date format — the mobile app reads it
For project-wide rules there's a dedicated file — AGENTS.md. A comment is good for pinpoint warnings next to a specific line.
Cleaning up the noise. Once AI has written the code, ask it to tidy up the notes:
Add commentsGo through this file. Delete comments that just retell the code. Keep and add only those that explain WHY: reasons for non-obvious decisions, traps, temporary patches. Delete commented-out code.By the way, telling a useful comment from noise is part of a bigger skill: reading code that AI wrote.
Do comments slow the program down?
No. The program simply skips them. And on websites, the build tool strips comments before shipping, so visitors don't even download them.
What language should comments be in?
Whatever language your team reads. For yourself — any language you like. For an open-source project, English is the norm.
How many comments is normal?
There's no right number. If a line is easy to misread without a note — write one. If the note duplicates the code — don't.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





