Hacker News Reader

Comment by areoform | Hacker News Reader

As a human who isn't a professional programmer, I've been writing comments like,

    // let's track age!!
    // this is harder than you'd think as I with totally impressive
    // foresight didn't add age to the raw data.
    //
    // More honestly, I didn't want to add age to the astro data as that's
    // a calculation that can change depending on how you slice it.
    //
    // Hence we need to figure out their age first.

Is that bad???

View on HN

I think this passes. In general "why" over "what". Give context to why something is made like it is (when seeming convoluted or strange). Sometimes I think one can give historical facts for really hairy hard to fix issues that have seen multiple iterations. But LLMs don't see these nuances. They frequently smuggle in completely irrelevant details in comments, e.g. including details from the given task context, not understanding what is relevant for the code module as a whole.

Edit: For API comments it's "what" of course, detailing the workings and contracts of the exported method, function or type, so one doesn't have to read the code to figure out how to use it.

// Workaround because we don’t have an age column in the db. See JIRA-1234

This would be better IMO :)

Most of the context belongs in a ticket. And the difficulty is subjective!

I'm mostly writing code for myself, but it's a project that'll end up being public and it'll be available for others to do whatever they want with. Does that change the answer?

I hate it when a comment tells me to see JIRA-1234. What if in a year's time we stop using Jira?

Far too often the answer has been that it doesn't matter, because the reason you stopped using Jira is the company stopped sending paycheques.

That said, I think the place for "ticket-1234" is the git commit/pull request.

Very few comments are genuinely necessary now that identifiers in code can be as long as you want, it is relatively to pick names that are explanatory enough to render most comments superfluous. 1% exceptions for unusual algorithms. (You're using named consts/enums rather than magic numbers, yes?)

personally it's fine and I've thanked myself many times for overly detailed comments coming up to some from 8 years ago and thinking how tf was I so smart/stupid (depending on the context)

Reply on news.ycombinator.com