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.
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.