39 ms·

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.

by 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

by js2 8y ago

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