3 ms·

The problem with that is you'll start reworking on a part of a project then you'll find something in the code and say, "Why was this done this way? It'd be so m

The problem with that is you'll start reworking on a part of a project then you'll find something in the code and say, "Why was this done this way? It'd be so much easier just to do this instead." Then you'll investigate further and find the commit that made the thing, read your commit message above and say, "Okay, why did I change this thing? I'm guessing it solved a problem at a time, but I don't know what the problem was." You'll decide: "I'm just going to pull this out and replace it with this easier thing". Then everything will work except for one thing, and you'll end up wasting days trying to sort out a weird corner case. Part way through that you'll come up with a solution that is more complicated then the easy refactor you tried to make and at some point you'll think, "Oh, that's why that was like that". You could have saved 3 days of work by just spending an extra 30 seconds to write the "Why" in your commit message. Your commit already includes the code changes (the "What"), so put a one/two sentence "Why" in your commit message.

koyote 5y ago
> Why was this done this way? It'd be so much easier just to do this instead If there is a reason for it being done 'this way' that is not obvious then there should be a comment in the code explaining the thought process. A commit won't really help you as much there as future refactoring might obscure the original commit that added the code. That being said, if there's some complexity in what is being solved I will usually add a very quick description of it in the commit message "Used XYZ algorithm to implement ABC due to it being faster/cleaner. See: ticket/wiki/documentation".
- m000 5y ago
  > there should be a comment in the code explaining the thought process Totally agree. Unofortunately, a descriptive git commit the best you can require without starting a religious war in the team. You won't believe how many developers zealously subscribe to the "no comments needed - good code is self-explanatory" crap. Or throw in the "comments will quickly become outdated" excuse.
  - soulofmischief 5y ago
    In my experience, the code produced by these kinds of coworkers is neither good nor self-explanatory.

koyote 5y ago

> Why was this done this way? It'd be so much easier just to do this instead If there is a reason for it being done 'this way' that is not obvious then there should be a comment in the code explaining the thought process. A commit won't really help you as much there as future refactoring might obscure the original commit that added the code. That being said, if there's some complexity in what is being solved I will usually add a very quick description of it in the commit message "Used XYZ algorithm to implement ABC due to it being faster/cleaner. See: ticket/wiki/documentation".

m000 5y ago
> there should be a comment in the code explaining the thought process Totally agree. Unofortunately, a descriptive git commit the best you can require without starting a religious war in the team. You won't believe how many developers zealously subscribe to the "no comments needed - good code is self-explanatory" crap. Or throw in the "comments will quickly become outdated" excuse.
- soulofmischief 5y ago
  In my experience, the code produced by these kinds of coworkers is neither good nor self-explanatory.