Code comments

Nothing compiles a comment and no test covers one, so comments drift away from the code while multiplying across files. Keep the ones that carry something the code cannot. Cut the rest.

Language-neutral: the rules hold for //, #, /* */, <!-- -->, docstrings, PHPDoc and JSDoc alike. A project's CLAUDE.md / AGENTS.md wins where it disagrees, and so does an existing convention in the surrounding file.

1. The test

Write the code first. Read it back as someone who has not seen it before. Add a comment only for what you could not work out from the code itself.

A comment earns its place when it carries one of these: