Comment by lionkor

Comment by lionkor 3 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.

bee_rider 3 days ago

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.

Reply View 1 reply

lionkor 3 days ago

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.

Reply View | 0 replies

Kwpolska 3 days ago

Git blame won't show you the history you care about if the line is changed in the future.

Reply View 1 reply

lionkor 3 days ago

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.

Reply View | 0 replies

omoikane 2 days ago

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

Reply View 2 replies

nneonneo 2 days ago

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.

Reply View | 0 replies
account42 2 days ago

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.

Reply View | 0 replies