[Someone1234]

Comments that say HOW commonly useless, as that is almost always self-evident (i.e. "just read the code."). Comments that explain WHY are worth their weight in gold, and not something AI could ever create.

For example:

    // How: This filters records by MyType of J and if they have children   
    // Why: We want Jobs (J) when those Jobs have Children. Otherwise, we'll get JobGroups or Jobs without any Children we need to process below.   
     .Where(T => T.MyType == "J" && T.Child.Count() > 0);  

WHY are, by their very nature, business rules or explaining a thought process. If the original developer of the code moves on or is unavailable, that information can sometimes not be found elsewhere.

[ugh123]

>and not something AI could ever create.

Really? You don't think it's a matter of updating the prompt and expanding the context to include more of the code?

I don't know the exact method of how they generated these comments, but I think just focusing a prompt on a single method with the entire codebase in context would yield much better results.

[phyzome]

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

[treffer]

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!

[phyzome]

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.

[nameless912]

90% of the comments in the codebase on the project I work on now are links to JIRA tickets and incident reports. AI can't and won't ever do that, and those comments are absolute gold. You can immediately read a seemingly less than optimal or overly defensive snippet of code, wonder "what moron wrote this!?" and then immediately read the referenced ticket and realize that it's "overly defensive" due to a caller that abused our API and caused it to fall over.

[welshwelsh]

You don't think it's possible to integrate an AI system with JIRA so that it can link to the relevant tickets?

[netsharc]

There are probably already IDE integrations so you can make Jira-like strings clickable to the appropriate task, or show a tooltip to hover.

It doesn't even need fucking AI, just regexp and just a configuration, e.g. if your Jira project is called NAI, any word that has the format NAI-[0-9]* should be such a link to https://jira.lookatmenotusingfancyai.com/task/NAI-xx

Edit: then again, Jira tasks can end up being a place for long discussions. If the AI can summarize the end-result/the decisions taken, it would be useful.. but also as a Jira plugin.

[LightFog]

Because the information leading to the comment is not necessarily in the code itself? E.g ‘we did this because of business constraint xyz’

[mjr00]

> Really? You don't think it's a matter of updating the prompt and expanding the context to include more of the code?

AI isn't magic. If the "why" isn't in the code, there's no way for it to magically synthesize it.

Comments explaining "there's a check for this edge case because we saw a problem in production when client X did something, see JIRA-1234 for more details" are what you should be aspiring to. If a human doesn't write that down, the AI can't invent it.