Comment by nneonneo

It’d be nice if comments were always updated, but the reality of it is that they often aren’t.

Sometimes it’s because the later developer doesn’t think the comment needs to be fixed - maybe they tried to fix a bug in John Doe’s approach, accidentally introduced a new bug, but thought they didn’t touch the clever algorithm.

Sometimes it’s because the comment isn’t proximate to the code it refers to. For example, in the “XYZ initializer” case, maybe XYZ is changed down the line to remove the ABC behaviour, but the comment stays because it is attached to some faraway usage of XYZ.

Notes in commit messages don’t fix either of these problems, obviously. But, on the other hand, they obviously refer to a specific point in time, unlike comments, which makes it easier to figure out if the notes are still relevant or not.