Comments should be metadata and not inline anyway.
Different people reading the same code would expect different comments and even the same person reading for different reasons would need different comments.
For example, do you want to know what the bit of code does? Or how it works? Or what about what to look out for? Or what makes it different from the rest? Or… So many different things comments can tell us, so many different needs for different developers. Of course it’s impossible to agree on a single standard. No one should even bother trying.
Instead we should be looking at comments as a type of annotation that lives outside the code, but then is put back inline by UX when and as needed.
The problem here is keeping comments in sync with what the code actually does. This tends to be a problem with all sorts of technical documentation like wikis and other knowledge bases. The more elaborate the comments get the higher the chance that some part of the comments doesn’t get updated when the code changes, and the only thing worse than not having comments is having misleading comments.
Comments can be associated with a single line or code block. The UX keeps track of when a code block has changed and reminds you to update it or marks it as possibly out of sync. Since comments are meta data you can also compare authors of code vs comments for Blame.
Comments should be metadata and not inline anyway.
Different people reading the same code would expect different comments and even the same person reading for different reasons would need different comments.
For example, do you want to know what the bit of code does? Or how it works? Or what about what to look out for? Or what makes it different from the rest? Or… So many different things comments can tell us, so many different needs for different developers. Of course it’s impossible to agree on a single standard. No one should even bother trying.
Instead we should be looking at comments as a type of annotation that lives outside the code, but then is put back inline by UX when and as needed.
The problem here is keeping comments in sync with what the code actually does. This tends to be a problem with all sorts of technical documentation like wikis and other knowledge bases. The more elaborate the comments get the higher the chance that some part of the comments doesn’t get updated when the code changes, and the only thing worse than not having comments is having misleading comments.
Comments can be associated with a single line or code block. The UX keeps track of when a code block has changed and reminds you to update it or marks it as possibly out of sync. Since comments are meta data you can also compare authors of code vs comments for Blame.
I’m sure that tooling could help, but I’m just pointing out that making good documentation and keeping it up to date is a non trivial problem.