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.
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.