comments
Comments and KDoc
The best comment is no comment
Default to writing none. A comment is not free and does not start neutral: it is a second thing to keep in step with the code, and only one of the two is checked by anything. The question is never "is this comment accurate?" — it is "would deleting it lose something the code cannot say?"
Most candidates fail that. Well under one inline comment per hundred lines is not an aspiration, it is simply what a file looks like once the bar is applied honestly.
The reason to be this strict is rot. Code is executed and tested, so it stays true. A comment is verified by nobody, and a wrong comment is worse than no comment because it is believed. Every comment you do not write is one that cannot go stale.
Apply the test before writing one: draft it, then delete it and read the code alone. If nothing became unknowable, it stays deleted. If the code only reads correctly with the comment, change the code instead — see Prefer changing the code.
The comment must clear that bar on its own. "It might help someone" does not; that is true of every sentence anyone could write about any line.