logoalt Hacker News

oneeyedpigeon • 12/09/2024 • 1 reply • view on HN

> comment why they added a particular dependency to their project

Surely that's what the commit message is for? I mean, I get that it's more convenient to have the comment right there in the file, but that should be balanced against the downsides: having to maintain the comment, making the file larger and more awkward to read, etc.

Replies

hn_throwaway_99 • 12/09/2024

Your rationale could apply to all comments in general. Hey, just have folks scour through the commit messages instead!

Yes, I still think a commit message is important, but it absolutely does not take the place of a comment. Suppose you'd like to do something like this:

    // DO NOT change to latest version. MUST pin to version 1.2.3 because
    // 1.2.4 includes a subtle bug that doesn't work with our version of
    // the zed library. We have an open issue on zed, see
    // https://github.com/zed/zed/issues/1234.
    // Once that is fixed, we can upgrade.
    "foobar": "1.2.3"
There is zero chance that comment is going to be seen if its just in a commit message, furthermore you should never depend on git blame showing a particular comment because it's easy for later commits to overwrite it due to simple things like formatting changes, etc. Yes, in that example case there should be tests too, but IMO the primary purpose for comments is to highlight issues and concerns that aren't immediately apparent just by reading the code.

I simply cannot think of another file format that is used for configs that doesn't support comments.

➕ show 1 reply