4 ms·

Yup, way too many times I’ve encountered code that’s written in a peculiar way obviously for a reason, most likely to work around some issue, but it’s not clear

by oefrha 6y ago

Yup, way too many times I’ve encountered code that’s written in a peculiar way obviously for a reason, most likely to work around some issue, but it’s not clear what the issue is and whether it is otherwise resolved so that the peculiar code can be dropped. I bisect and it says “fix bug”, now I need to carry that crap forever or worry about reintroducing some unknown bug. (In case someone points out a comment is more suitable: comments are less likely to survive refactors, and people who write terrible commit messages also tend to be terrible commenters. Informative commit messages supplement good comments.)

heavenlyblue 6y ago
Why is the reason to peculiarity not in the comments in the code itself?
- usrusr 6y ago
  Comments aren't supposed to state the obvious and at the time it probably was. Commit messages are redundant by definition (everything said in the message is supposedly already there in the diff) so they are like magnets for stating the seemingly obvious.
  - u801e 6y ago
    > Commit messages are redundant by definition (everything said in the message is supposedly already there in the diff) Commit messages are far easier to parse and understand compared to a moderate size diff. By reading the commit message before looking at the diff, it really helps in terms of understanding the context of the diff and what to expect.
    - greyhair 6y ago
      More than that, I find moderately sized 'git' diffs in PRs to be unreadable. I frequently have to open the full code block to see what is taking place in the source. Commit messages provide intent, and should reference the original change request to see what the commit was intended to fix. I would say the whole chain matters. A good change request (Jira) with defects, and how to recreate the fault, as well as relevant requirements (by reference, not cut-n-paste) Good comments on the code that is changing. Don't document the defect and how you fixed it, just comment what the code does (if the code is not perfectly clear), Then a good commit message, referencing the change request, to tie it all together. It all matters.

by oefrha 6y ago

heavenlyblue 6y ago

Why is the reason to peculiarity not in the comments in the code itself?

usrusr 6y ago
Comments aren't supposed to state the obvious and at the time it probably was. Commit messages are redundant by definition (everything said in the message is supposedly already there in the diff) so they are like magnets for stating the seemingly obvious.
- u801e 6y ago
  > Commit messages are redundant by definition (everything said in the message is supposedly already there in the diff) Commit messages are far easier to parse and understand compared to a moderate size diff. By reading the commit message before looking at the diff, it really helps in terms of understanding the context of the diff and what to expect.
  - greyhair 6y ago
    More than that, I find moderately sized 'git' diffs in PRs to be unreadable. I frequently have to open the full code block to see what is taking place in the source. Commit messages provide intent, and should reference the original change request to see what the commit was intended to fix. I would say the whole chain matters. A good change request (Jira) with defects, and how to recreate the fault, as well as relevant requirements (by reference, not cut-n-paste) Good comments on the code that is changing. Don't document the defect and how you fixed it, just comment what the code does (if the code is not perfectly clear), Then a good commit message, referencing the change request, to tie it all together. It all matters.