Comment by lionkor
2 days ago
I really like putting context into commits, not into code comments. The reasoning is pretty simple: Comments aren't checked. I might write "This is done this way because John Doe suggested it, it's much more efficient this way", and then someone else changes the code to be buggy, wrong, and slow. Now, the comment is explaining behavior that is no longer there, and wrongly suggests that the code does/means something it doesn't.
Another argument is comments-as-noise, as I would call it. The more "unnecessary" comments you write, the more core developers (who write and read most of the code), will learn to ignore comments. Then, critical comments like "Be careful not to call this when XYZ isn't initialized yet, unless you don't mind ABC happening" are ignored, and ta-da! comments are now useless.
Commit messages are attached to specific changes. If I want to know why a line of code is the way it is, I can git blame it, and see which commit is to blame, together with issue numbers, authors, maybe reviewers, context, history, etc.
Should there be a comment briefly explaining this patch? Probably. But the commit message should add the other context.
Maybe there should be a convention around comments which describe functionality, those which describe history, and I’m sure we can find other types of comments. Then we can have our editors hide certain types of comments based on what we want to see.
The issue is really that the comments' semantics aren't validated. That might be an AI startup idea; going through a codebase and linting comments.
Git blame won't show you the history you care about if the line is changed in the future.
It does, you can use various parameters to go through the history of a line of code. And, usually, you only care about why it is the way it is.
I think this is saying there is a habit of updating code without reading and updating the comments associated with the code. I would argue the fix is to have people get in the habit of maintaining comments, as opposed to not writing any comments at all.
If people already have the habit of ignoring comments that are right there in the code, I am not sure they would spend the extra effort to go after commit history. Also, some commits might have originated from private repositories where commit history is not accessible, and the most context we get out of "git blame" might be "code was imported on this date".
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.
You don't have any control over the people who touch the code after you so you cannot "fix" the risk that someone updates your code without the comment. You do have control over your own commit though.