undefined | Better HN

0 pointsphyzome2y ago0 comments

"Why" comments typically refer to things outside of the actual code, such as:

* Past incidents

* Regulations

* What the code used to do, and why that was bad

The whole point of a really good comment is that you can't infer it just by looking at the code. That's why it's there at all!

0 comments

treffer2y ago

This should IMHO summarized in the related git commits.

Yes they become paragraph long. But that's the point. That's where I search for "why". And not just "why", "when, why and with what reasoning?".

Imagine if there were some interference that could derive a comment based on history and current code!

phyzomeOP2y ago

Commit messages aren't a great place for this, much of the time, because then you have to do archaeology just to figure out why something is the way it is.

I'm certainly a fan of including lots of detail in commit messages, but often I do so and then realize "hey, this particular information would be better situated close to the code", and I move it.

Other times, yes, it's really just best to leave in the commit message because no one looking at the after-version of the code will care. For example, removal of a deprecated feature.

j / k navigate · click thread line to collapse