I miss the most important one. Explain business reasons.
Code does what it's written for. But it does not explain intent. Write that on a comment, link to the relevant ticket and document
Code does what it's written for. But it does not explain intent. Write that on a comment, link to the relevant ticket and document
I very often nudge people to remove their comments entirely. Less experienced devs often write comments to explain code, instead of spending time on making the code itself readable/understandable. I often ask: “Can you modify the code such that the comment will become obsolete?”
Comments there will be tied to that version of the code, can never go out of sync.
It's also good to learn how that piece of code evolved and what reasons to change. Avoids repeating past mistakes.
Yes, code should be easy to understand.
But well-written comments that explain assumptions and intent helps as code evolves over time.
Also, comments are quicker to scan than code itself.
A good comment can indicate code that can be ignored for the purposes of certain troubleshooting.
Finally, junior developers usually write code that is difficult to understand and don't comment.
I've rarely ever seen a junior developer that both writes unreadable code and takes the time to write comments.
Usually comments are a sign of seniority, someone who has pity on those who will come after him/her.
And thus that person tends to also write understandable code.
Perhaps there's an uncanny valley in between where comments are a band-aid for complexity, but I have never observed that in years of working with many developers.
It's also a misguided tools upgrade if they have no way to redirect, convert or otherwise handle old links.
If you link to Sharepoint or something it's useless as soon as that link changes.
But make the boss understand...
Normally the comment is an explanation of the intent but the referenced ticket has the full discussion and backing data that led to the decision
Bigger architecture decisions should go in ADRs (again, explain the why) but smaller stuff like explaining why you monkeypatched a library can save future devs a lot of lost investigation time and pain. Maybe by the time they are reading your comment/code, the patch you wrote is supported in the main library!