5 ms·

Many people write the 'What' in comments, which is redundant, as we can see the code. Some document the 'How' but this can be deduced from the code except when

Many people write the 'What' in comments, which is redundant, as we can see the code. Some document the 'How' but this can be deduced from the code except when using very clever algorithms. Seldom people document the 'Why' which is the most useful some years in as no one knows the 'Why' any longer and might make the wrong decisions in refactoring - also if you don't know the 'Why' you often scratch your head with WTF, though the reasons were sound.

masklinn 8y ago
I prefer having the "why" in commit messages than in comments, unless it's something really screwy and needs a big warning right there. "How" though, very much e.g. reference to the algorithm being implemented or the like if the code is unclear.
- xyzzy_plugh 8y ago
  Spending copious time spelunking through commit logs to find the reason something exists would be better replaced by a succinct comment pointing the reader in the right direction. Not to mention the misery one feels when they discover that oh, there is in fact no reason at all, or if there ever was, it is now truly lost.
  - edejong 8y ago
    My IDE allows me to easily annotate each line with author and commit message. Invaluable information.
    - catmanjan 8y ago
      What if someone changes the line? You lose the useful commit message
      - masklinn 8y ago
        VCS UI generally have a way to re-annotate the previous revision (even "git gui" does), if the code was changed since the original commit but the change is not what I'm concerned with. More often than not, you only need a few jumps before reaching the change you're interested in.
    - maccard 8y ago
      The file I have open right now is 1500 lines with probably 400 revisions across numerous branches. Many of those revisions are going to be integrates across branches. How is my IDE supposed to know which of those revisions are the ones that I care about? And more to the point, how is it supposed to do that _quickly_ ?
      - masklinn 8y ago
        > The file I have open right now is 1500 lines with probably 400 revisions across numerous branches. I have a 1500LOC files with 1100 revisions right here, "git annotate" processes it in 2.356 seconds on a 2010 MBP, and PyCharm barely takes any longer (maybe 3s). > How is my IDE supposed to know which of those revisions are the ones that I care about? It does not care, it gives you a baseline annotation and if that's too recent you drill down into previous annotations.
        maccard 8y ago
        > (maybe 3s) > you drill down into previous annotations No thanks. I’d rather have a comment inline in the code than add 3 seconds per file, and still have to go searching through the history.
        glenneroo 8y ago
        What happens when your version control dies? Of course it shouldn't happen, but we all know about Murphy's Law. Or as I've encountered on multiple occasions: your IT team is struggling to figure out why your network/version control/etc are extremely slow... 3 second queries are now taking 60 seconds... we will be rebooting servers a few times... and restoring backups... hopefully things are working better tomorrow! Or what happens when you migrate to another versioning system? Where I was working migrated from MS SourceSafe years ago and a lot of comment history was lost in the conversion and apparently it wasn't worth the time/money to figure out why only half the comments made it over. I'm sure there are more scenarios. The point is: comments in plain-text source files can be invaluable.
        maccard 8y ago
  - masklinn 8y ago
    > Spending copious time spelunking through commit logs That's what annotate/blame is for. > Not to mention the misery one feels when they discover that oh, there is in fact no reason at all, or if there ever was, it is now truly lost. If there was "no reason at all", it won't be in a comment either.
- pm215 8y ago
  My rule of thumb is that "why did we change this?" goes in a commit message, and "why is this like this?" goes in a comment. The latter is less often necessary than the former, but if the reader of the code would otherwise spend five minutes puzzling it out, or worse, would remove an apparently incorrect bit of code, it's worth the effort of the comment.
  - _Codemonkeyism 8y ago
    Yes, same here.
- olavk 8y ago
  This seems wrong to me. If the "why" is not obvious from the code itself then it should be clearly explained in comments. It should not be detective work to figure out why some code is written in a non-obvious way. Otherwise people will be afraid to improve code.
  - masklinn 8y ago
    > If the "why" is not obvious from the code itself then it should be clearly explained in comments. Except you can't trust comments. Even assuming the comments were relevant at one point, they don't get updated as the code changes, and as new code gets added they can drift away from the original code they were supposed to explain. Commit messages don't drift, they're immutably bound to the changes the commit performs. And because they're not bloating up the code it's much easier to be clear and verbose in commit messages than it is in comments, the author can easily explain things which seem obvious to them but may not be so for a reader in a few months or years without lowering the overall readability of the code which is not the case of comments. People will criticise comments as "obvious" and "unnecessary", I've yet to have a colleague or contributor criticise a detailed commit message for any other reason than the commit message being wrong. > It should not be detective work to figure out why some code is written in a non-obvious way. Get proper tools. Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory.
    - cesarb 8y ago
      > Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory. That works until the VCS history is lost. For an on-topic example, this usually happens when a formerly closed-source code is released to the public: only the final state of the source code is released, with none of the VCS history. This can also happen when changing to another VCS; often the history is kept only on the former VCS. Some projects have gone through several of these events; I challenge you to find early StarOffice history when trying to understand why some piece of LibreOffice code is written that way. And there's also the tendency in some places to reference bug tracker issues in commit messages. Said bug trackers tend to have an even shorter life than the VCS. "Fixes issue #1234" is useless when issue 1234 was on the old bug tracker, and both it and the new bug tracker were lost when the company was acquired and migrated to a third bug tracker.
- duxup 8y ago
  As someone just learning coding I'm finding myself drifting from what to why a great deal more in my own code, if only because I can read the what a bit easier now than in the past .... and the why concerns me more now. "Doing this here because x,y,z, maybe better to do a,b,c later on but would have to do d,e,f" and so on. I do worry a bit about doing it sometimes because in its own way it admits some sort of shortcomings or such... but still I do it. When reading other people's code the why is often the question I'm wondering but rarely anyone says.

masklinn 8y ago

I prefer having the "why" in commit messages than in comments, unless it's something really screwy and needs a big warning right there. "How" though, very much e.g. reference to the algorithm being implemented or the like if the code is unclear.

xyzzy_plugh 8y ago
Spending copious time spelunking through commit logs to find the reason something exists would be better replaced by a succinct comment pointing the reader in the right direction. Not to mention the misery one feels when they discover that oh, there is in fact no reason at all, or if there ever was, it is now truly lost.
- edejong 8y ago
  My IDE allows me to easily annotate each line with author and commit message. Invaluable information.
  - catmanjan 8y ago
    What if someone changes the line? You lose the useful commit message
    - masklinn 8y ago
      VCS UI generally have a way to re-annotate the previous revision (even "git gui" does), if the code was changed since the original commit but the change is not what I'm concerned with. More often than not, you only need a few jumps before reaching the change you're interested in.
  - maccard 8y ago
    The file I have open right now is 1500 lines with probably 400 revisions across numerous branches. Many of those revisions are going to be integrates across branches. How is my IDE supposed to know which of those revisions are the ones that I care about? And more to the point, how is it supposed to do that _quickly_ ?
    - masklinn 8y ago
      > The file I have open right now is 1500 lines with probably 400 revisions across numerous branches. I have a 1500LOC files with 1100 revisions right here, "git annotate" processes it in 2.356 seconds on a 2010 MBP, and PyCharm barely takes any longer (maybe 3s). > How is my IDE supposed to know which of those revisions are the ones that I care about? It does not care, it gives you a baseline annotation and if that's too recent you drill down into previous annotations.
      - maccard 8y ago
        > (maybe 3s) > you drill down into previous annotations No thanks. I’d rather have a comment inline in the code than add 3 seconds per file, and still have to go searching through the history.
      - glenneroo 8y ago
        What happens when your version control dies? Of course it shouldn't happen, but we all know about Murphy's Law. Or as I've encountered on multiple occasions: your IT team is struggling to figure out why your network/version control/etc are extremely slow... 3 second queries are now taking 60 seconds... we will be rebooting servers a few times... and restoring backups... hopefully things are working better tomorrow! Or what happens when you migrate to another versioning system? Where I was working migrated from MS SourceSafe years ago and a lot of comment history was lost in the conversion and apparently it wasn't worth the time/money to figure out why only half the comments made it over. I'm sure there are more scenarios. The point is: comments in plain-text source files can be invaluable.
        maccard 8y ago
- masklinn 8y ago
  > Spending copious time spelunking through commit logs That's what annotate/blame is for. > Not to mention the misery one feels when they discover that oh, there is in fact no reason at all, or if there ever was, it is now truly lost. If there was "no reason at all", it won't be in a comment either.
pm215 8y ago
My rule of thumb is that "why did we change this?" goes in a commit message, and "why is this like this?" goes in a comment. The latter is less often necessary than the former, but if the reader of the code would otherwise spend five minutes puzzling it out, or worse, would remove an apparently incorrect bit of code, it's worth the effort of the comment.
- _Codemonkeyism 8y ago
  Yes, same here.
olavk 8y ago
This seems wrong to me. If the "why" is not obvious from the code itself then it should be clearly explained in comments. It should not be detective work to figure out why some code is written in a non-obvious way. Otherwise people will be afraid to improve code.
- masklinn 8y ago
  > If the "why" is not obvious from the code itself then it should be clearly explained in comments. Except you can't trust comments. Even assuming the comments were relevant at one point, they don't get updated as the code changes, and as new code gets added they can drift away from the original code they were supposed to explain. Commit messages don't drift, they're immutably bound to the changes the commit performs. And because they're not bloating up the code it's much easier to be clear and verbose in commit messages than it is in comments, the author can easily explain things which seem obvious to them but may not be so for a reader in a few months or years without lowering the overall readability of the code which is not the case of comments. People will criticise comments as "obvious" and "unnecessary", I've yet to have a colleague or contributor criticise a detailed commit message for any other reason than the commit message being wrong. > It should not be detective work to figure out why some code is written in a non-obvious way. Get proper tools. Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory.
  - cesarb 8y ago
    > Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory. That works until the VCS history is lost. For an on-topic example, this usually happens when a formerly closed-source code is released to the public: only the final state of the source code is released, with none of the VCS history. This can also happen when changing to another VCS; often the history is kept only on the former VCS. Some projects have gone through several of these events; I challenge you to find early StarOffice history when trying to understand why some piece of LibreOffice code is written that way. And there's also the tendency in some places to reference bug tracker issues in commit messages. Said bug trackers tend to have an even shorter life than the VCS. "Fixes issue #1234" is useless when issue 1234 was on the old bug tracker, and both it and the new bug tracker were lost when the company was acquired and migrated to a third bug tracker.
duxup 8y ago
As someone just learning coding I'm finding myself drifting from what to why a great deal more in my own code, if only because I can read the what a bit easier now than in the past .... and the why concerns me more now. "Doing this here because x,y,z, maybe better to do a,b,c later on but would have to do d,e,f" and so on. I do worry a bit about doing it sometimes because in its own way it admits some sort of shortcomings or such... but still I do it. When reading other people's code the why is often the question I'm wondering but rarely anyone says.