3 ms·

In my opinion the why belongs into the commit message not into a comment. Whys are usually highly context-dependent and you should not include all the context

• ryanbrunner 14y ago
  Assuming that the solution is always obvious from the code is naive and dangerous. You should always strive to make code speak for itself, but there's occasionally cases that require you to do something unintuitive for some reason or another, and comments serve as a useful warning sign or explanation for future programmers (something that a commit message is uniquely unsuited for) Going through a few files on one of my codebases, here's some of the useful comments that I can find from a quick skim: - Explaining why a dummy argument existed on a method (a third-party library required it) - Explaining why we need to set a weird inheritance column on an ActiveRecord model (we're using 'type' as an actual column) - Calling out some technical debt that could be fixed by someone at some point. All of these are really about calling out why the solution is not obvious.
• pm215 14y ago
  My rule of thumb is that you can't expect people reading the code to go diving into the revision control history. So if a reader of the code needs the information, it goes in a comment. Commit messages justify the change; comments justify the code as it stands. I think these are different kinds of 'why' (though they can certainly often overlap a lot).