4 ms·

One big issue with code comments that hasn't been mentioned yet: they tend to run out of sync with the actual code. That is, whenever changes to the program ar

by kleiba 8y ago

One big issue with code comments that hasn't been mentioned yet: they tend to run out of sync with the actual code. That is, whenever changes to the program are made, you are now required to also update the comment but a lot of times that last step is skipped. One may ask what's worse: the absence of comments or _outdated_ comments that no longer match the code.

nostrademons 8y ago
This is less of a problem if you comment for the "why" rather than the "what" or "how". The "why" generally doesn't change much over time, and if it does, it's usually blatantly apparent that the comment makes no sense in the new reality.
js2 8y ago
The fact that someone might not keep the comments up to date in the future is no excuse for not writing the comments now, otherwise we'd never write comments. For hairy code, I'd rather have an out of date comment than none at all. I can recall a lot more times wishing code was commented than having encountered a stale comment. And especially today, when code is usually in a VCS where you can blame the lines, it's not that hard to double-check if a comment seems off. So, I think the absence of comments is far worse.
- procinct 8y ago
  If the code doesn’t function exactly as a comment suggests how do you go about determining if the comment is wrong (or out of date) or the code?
  - js2 8y ago
    By the expected behavior of the program? By checking the VCS commit log/blame? How would you determine what to do for a misbehaving function with no comment? This seems like a hypothetical question to which the only answer I can give is: it depends.
  - cbsks 8y ago
    “git blame”, is what I usually reach for
    - AstralStorm 8y ago
      Its politically correct name is git annotate. ;)
      - js2 8y ago
        I don't think PC had anything to do with it. Git blame and annotate were added at the same time, have slightly different output, and different provenances[1,2]. The differing names are because the commands were inspired from prior VCSs that had different names for the commands. Also, from the git annotate man page[3]: The only difference between this command and git-blame is that they use slightly different output formats, and this command exists only for backward compatibility to support existing scripts, and provide a more familiar command name for people coming from other SCM systems. [1] https://github.com/git/git/commit/cbfb73d73f272f194bafa70d5be1f35abc265c79 https://github.com/git/git/commit/cbfb73d73f272f194bafa70d5b... [2] https://github.com/git/git/commit/c65e898754ef68a5520b2791890dda51753d00c6 https://github.com/git/git/commit/c65e898754ef68a5520b279189... [3]https://www.git-scm.com/docs/git-annotate https://www.git-scm.com/docs/git-annotate
techbio 8y ago
It can be an incredible waste of time to code based on an outdated comment, especially since changes made after a method is created are likely both subtle and required by a new design version. That said, I wonder why ie. JavaDoc doesn't raise at least an informational message when a code block has changed, but its comment has not. Are there IDE features that support this?
yawaramin 8y ago
It has been mentioned. See https://github.com/pingcap/community/blob/master/code-comment-style.md#tips-for-a-good-comment https://github.com/pingcap/community/blob/master/code-commen... : > Make sure the comment is up-to-date

by kleiba 8y ago

nostrademons 8y ago

This is less of a problem if you comment for the "why" rather than the "what" or "how". The "why" generally doesn't change much over time, and if it does, it's usually blatantly apparent that the comment makes no sense in the new reality.

js2 8y ago

The fact that someone might not keep the comments up to date in the future is no excuse for not writing the comments now, otherwise we'd never write comments. For hairy code, I'd rather have an out of date comment than none at all. I can recall a lot more times wishing code was commented than having encountered a stale comment. And especially today, when code is usually in a VCS where you can blame the lines, it's not that hard to double-check if a comment seems off. So, I think the absence of comments is far worse.

procinct 8y ago
If the code doesn’t function exactly as a comment suggests how do you go about determining if the comment is wrong (or out of date) or the code?
- js2 8y ago
  By the expected behavior of the program? By checking the VCS commit log/blame? How would you determine what to do for a misbehaving function with no comment? This seems like a hypothetical question to which the only answer I can give is: it depends.
- cbsks 8y ago
  “git blame”, is what I usually reach for
  - AstralStorm 8y ago
    Its politically correct name is git annotate. ;)
    - js2 8y ago
      I don't think PC had anything to do with it. Git blame and annotate were added at the same time, have slightly different output, and different provenances[1,2]. The differing names are because the commands were inspired from prior VCSs that had different names for the commands. Also, from the git annotate man page[3]: The only difference between this command and git-blame is that they use slightly different output formats, and this command exists only for backward compatibility to support existing scripts, and provide a more familiar command name for people coming from other SCM systems. [1] https://github.com/git/git/commit/cbfb73d73f272f194bafa70d5be1f35abc265c79 https://github.com/git/git/commit/cbfb73d73f272f194bafa70d5b... [2] https://github.com/git/git/commit/c65e898754ef68a5520b2791890dda51753d00c6 https://github.com/git/git/commit/c65e898754ef68a5520b279189... [3]https://www.git-scm.com/docs/git-annotate https://www.git-scm.com/docs/git-annotate

techbio 8y ago

It can be an incredible waste of time to code based on an outdated comment, especially since changes made after a method is created are likely both subtle and required by a new design version. That said, I wonder why ie. JavaDoc doesn't raise at least an informational message when a code block has changed, but its comment has not. Are there IDE features that support this?

yawaramin 8y ago

It has been mentioned. See https://github.com/pingcap/community/blob/master/code-comment-style.md#tips-for-a-good-comment https://github.com/pingcap/community/blob/master/code-commen... : > Make sure the comment is up-to-date