News for hackers. Stuff that matters.
Re:TLDR explains what a piece of code does by hn_throwaway_99 on Thursday September 22, 2022 @06:54PM (#32945674)
FWIW, when I'm doing a code review, these are the exact kind of comments that I would tell a committer to remove.

That is, it's like it generates these kinds of comments:

    // initializes the variable x and sets it to 5
    let x = 5;

    // adds 2 to the variable x and sets that to a new variable y
    let y = x + 2;
That is, IMO the whole purpose of comments should be to tell you things that aren't readily apparent just by looking at the code, e.g. "this looks wonky but we had to do it specifically to work around a bug in library X".

Perhaps could be useful for people learning to program, but otherwise people should learn how to read code as code, not "translate" it to a verbose English sentence in their head.

Re:TLDR explains what a piece of code does by eyelidlessness on Thursday September 22, 2022 @07:22PM (#32945937)
I don’t think the intent of this tool is to generate comments which you’d then embed into the code it describes. I think it’s meant to explain, in plain language, what the actual behavior is (for whatever confidence level you might assign to “actual” and “is”).

To your point about the utility of code comments describing the behavior this way, I agree it’s probably much more valuable for beginners. In fact when I’ve mentored early programmers, I sometimes ask them to write out essentially prose like this in comments before writing a single line of executable code.

Now, I’m far from a beginner. I’ve been considered a senior engineer long enough that friends discourage me from disclosing the amount of time, for fear of age discrimination. I can absolutely see the potential of this tool as part of my IDE. I’m on vacation now, but when I return to work I plan to take it for a spin as an aid for refactoring areas of code which clearly work as intended (well, for the most part) but the actual behavior and intent is much less clear.

Here’s why I think it’ll be valuable for refactoring: it can help limit the amount of mental context switching necessary to build a mental model of what the code does. I often find myself trying to produce prose much like this for my own reference, but I end up losing context as fast as I acquire it as I follow references into their respective rabbit holes. Having the tool do that for me can help me stay in a single area of focus. It could also be a useful reference for adding and improving type definitions, maybe even regression tests.

The best part is that it doesn’t, from what I’ve seen, do anything besides populate ephemeral annotations. It doesn’t try to write code or automate anything other than producing a narrative. Like at least one other commenter, I’m skeptical about the reliability of that. But unlike that commenter, I’m willing to take the risk… probably because I’ve learned to be skeptical of my own reliability performing the same task. If my instinct is right that I can use this tool the way I hope, I’ll still scrutinize it for accuracy. But that’s potentially much better than having only one imperfect, meat-based computer doing the work.

Re:TLDR explains what a piece of code does by hn_throwaway_99 on Thursday September 22, 2022 @07:51PM (#32946146)
To be clear, I'm not really arguing that the intent is to embed comments. But I'm just going by the "validateSignature" example they give in the video. All that does is generate a 1-1 mapping of each code line to an English comment. TBH I would expect a senior developer to just be faster reading the code.

Perhaps there are some other examples that explain more of a "structural understanding" of the code, but I'm skeptical without more evidence.

Re:TLDR explains what a piece of code does by patrec on Friday September 23, 2022 @05:34AM (#32949718)
> TBH I would expect a senior developer to just be faster reading the code.

TBH, I would also expect this tool to be a lot more affordable than a senior developer for language X.

Plus, chances are good that your senior developer for language X will barely scrape by as an extremely junior developer for language Y that you also use in some capacity, and that there is a problem which involves stuff written in both X and Y. Also, many languages have horrid gotchas, where innocuous looking code does something quite unexpected. Like the C++ classic log->debug("Timeout: %d", config["timeout"]). If some tool where to actually tell you "Writes a debug log with the current value of timeout, if it exists, or otherwise sets it to 0", well that would be pretty useful for someone who has only superficial knowledge of C++.

Re:TLDR explains what a piece of code does by eyelidlessness on Thursday September 22, 2022 @09:09PM (#32946769)
> TBH I would expect a senior developer to just be faster reading the code.

That specific code? Sure. Real world code that’s gotten more convoluted over a decade of maintenance?

I have a dozen pages of notes I’ve taken on the apparent behavior of a single function, all of its call sites, all of the known possible kinds of states it might encounter, all of the categories of implications those states might carry and the kinds of downstream effects its return value might have. It’s not even a particularly large function as far as those go. The notes aren’t even complete, if I had to guess they’re 1/3 there. To be complete they’ll span not just several modules but cross package and language boundaries and even repo migrations. Not because the function itself is that complex (although it’s much more complex than I’d prefer), but because the universe of its inputs and usage is enormous and the history which produced it is long and just as convoluted. And, importantly, because the space of very similar behaviors and functions I’ve discovered has grown each time I peel a layer of the onion off.

Now when I go back to work, given I get to continue untangling this thing, having a tool which helps even explain this universe would be a godsend for actually acting on it in a reasonably safe way. Especially if it does so with consistent language. I could literally shove it into a database and query it, or do all kinds of other analysis. I can’t do that if I’m spending all of my energy trying to just describe the thing in my own words with incomplete understanding. I mean, I can. The documentation I’m describing literally began with me wrapping up the previous day’s notes with “humans built this, a human can understand it, model the damn thing”. But on what timeline? And is it a good use of my time to do it when a machine could probably do it more quickly and hopefully just as reliably at scale?

I’d be happy to share the evidence if my instinct proves out.

Re:TLDR explains what a piece of code does by lupire on Thursday September 22, 2022 @10:29PM (#32947293)
I'm sympathetic but it seems like you are wishing for something that this toll can't do.
Re:TLDR explains what a piece of code does by eyelidlessness on Thursday September 22, 2022 @10:46PM (#32947423)
Really? The thing it does in the video is almost identical to something I’ve spent days doing manually. Even if it's a small part of the task, it does it in about a second. Why do you think it doesn’t do what I think it does?
Re:TLDR explains what a piece of code does by xyzzy123 on Thursday September 22, 2022 @11:15PM (#32947600)
The problem with complex code is usually branches / conditionality.

Also complex indexing or expressions.

This stuff very rapidly stops being expressible in narrative form because the details can't be "compressed".

The explanation starts to look like legalese and you realise the code itself is the more compact and legible expression.

Ideally an autocommenter will be able to take a hand matmult and write "compute the surface normal" (this is an example where apparently high local detail can map to good conceptual compression) but actually that is the best possible case.

When it comes to important but somewhat arbitrary stuff like shipping or tax rules, english will not speed comprehension and is less good than a tageted dsl or well thought out tables.

The core problem is that "sometimes there is no simple explanation".

Re:TLDR explains what a piece of code does by eyelidlessness on Friday September 23, 2022 @12:32AM (#32948084)
That’s all fine and good but the code exists already and even if I think its domain is an exceptionally good candidate for a DSL I can’t snap my fingers and make it morph into what I wish it was. And I can’t get there gradually without understanding what it is.

I’m well acquainted with its complexity but I need to articulate it coherently to justify changing any of it, not just to myself but to my team and stake holders. I’m not looking for a simple explanation. I’m looking forward to having tools help me navigate a very complicated explanation.

I also don’t understand the motivation here or upthread to splain the problem I’m solving away as some nihilistic unsolvable thing when I’m saying I see real prospects of this helping me. I mean, you’re welcome to whatever nihilism you see fit in your course of action but I personally don’t benefit from being told things I find potentially useful are not useful for me, actually.

Re:TLDR explains what a piece of code does by xyzzy123 on Friday September 23, 2022 @12:48AM (#32948180)
More power to you if it's helpful to you.
Re:TLDR explains what a piece of code does by alpaca128 on Friday September 23, 2022 @04:58AM (#32949511)
So a better "output" might be a kind of chatbot that will answer questions about that particular piece of code. Basically it understands every detail including branches and you can ask whether a specific assumption is correct.

I don't think we're there yet (because complicated side effects etc. are a thing) but I would rather have such a solution than some text to read, after all I'd be using such a tool for code I cannot comprehend just by reading it.

Re:TLDR explains what a piece of code does by bjterry on Friday September 23, 2022 @01:10AM (#32948288)
It's possible that if you changed from translating the code to prose by hand and translating it with the tool, you would find that the "value" of that translation would be reduced. Basically, I think reading the code and mentally analyzing it enough to write to prose is doing most of the work, and when you read the prose, it's only a reminder for the deeper analysis you've done in your head.
Re:TLDR explains what a piece of code does by eyelidlessness on Friday September 23, 2022 @02:43AM (#32948780)
It’s possible that you’re being a well meaning jerk. I said why I’d value it. Why not just let me value it?
Re:TLDR explains what a piece of code does by viceroyalbean on Thursday September 22, 2022 @08:22PM (#32946393)
Yeah, I find the signature example kind of unimpressive because it can just pick up the meaning of the code from the function name and variables, which an experienced human can do just as easily. If it could get "validates a signature with secret key" when all the variable names are obfuscated it might be useful in some code bases.
Re:TLDR explains what a piece of code does by khitchdee on Thursday September 22, 2022 @07:40PM (#32946070)
Why could you not create a comment block above the code section in question and fold it. All IDE's nowadays support folding, including comment block folding. To see what a section of code does, you unfold the comment block above it, read it, then fold it back.
Re:TLDR explains what a piece of code does by danielvaughn on Thursday September 22, 2022 @07:48PM (#32946125)
But if it can be generated on the fly, why persist it to the code at all?
Re:TLDR explains what a piece of code does by khitchdee on Thursday September 22, 2022 @08:11PM (#32946299)
I guess if the AI is good enough, your point makes some sense. It's a good programming habit to doc your code as you write it. If you do this in a structured way and code folding is used the comments should get out of the way from the main code.
Re:TLDR explains what a piece of code does by darkwater on Friday September 23, 2022 @03:42AM (#32949072)
To save computational resources could be an answer.
Re:TLDR explains what a piece of code does by noufalibrahim on Friday September 23, 2022 @01:57AM (#32948541)
I completely agree with your point here. The extreme pathological case is when you see things like this

   i += 2 // Increments i by 1
Now you're screwed. Added bonus - the commit message introducing this change is "Yay! Fixed all the tests!!!!"
Re:TLDR explains what a piece of code does by petemir on Friday September 23, 2022 @03:26AM (#32948986)
The Fortune bash command was kind enough to provide me with this yesterday:

"When code and comments disagree, both are probably wrong", Norm Schryer.

Re:TLDR explains what a piece of code does by halopro77 on Friday September 23, 2022 @02:37AM (#32948755)
pls no, stop
Re:TLDR explains what a piece of code does by version_five on Thursday September 22, 2022 @08:02PM (#32946238)
Another way to look at it is that it doesnt (afaik) have externsl context, so there are severe limits on what it could possibly infer from some code. Like you say, if something unusual is being done because of a library, or business rules or something, "AI" cannot take this into account. There may be some cases where something non-obvious can be distilled out of the code, though I agree that mostly the stuff you can infer without context is mostly self evident from the code anyway

Edit: just thinking, the canonical example would be something like the fast inverse square root from quake. Is it going to summarize or is it going to tell you

  i = 0x5f3759df - (i >> 1);

  // Shift i right by one and subtract it from 0x5f...
(It would be cool if it does work here, even if it does, when someone makes up a new thing like this, it couldn't possibly comprehend why it's being done)
Re:TLDR explains what a piece of code does by Timpy on Thursday September 22, 2022 @08:26PM (#32946420)
Fortunately for me, at my current job I don't see a lot of code that makes me say "what the hell is this even trying to do?" The most useful comments are the ones explaining limitations and why this implementation was chosen, or business rules that wouldn't be apparent in the code.
Re:TLDR explains what a piece of code does by Izkata on Friday September 23, 2022 @09:11AM (#32951432)
Summarized by the common advice "comments should explain the why, not the what/how".
Re:TLDR explains what a piece of code does by dogcomplex on Thursday September 22, 2022 @09:21PM (#32946849)
Seeing as how its knowledge base is pulled from similar code pulled from the internet, I'd find it very likely to get the reference and interpret that as the quake fast inverse square root. Same with general context/library stuff - though obviously that's conditional on the quality of its training data.

e.g. it would probably "understand" common devops/organization/OS/library stuff even if it's not part of the language it's presumably reading - just because other users probably left comments on those lines similarly - but it's not gonna necessarily understand your application-specific business logic beyond what's actually happening. Would need some very specific examples though (by definition lol). Even dumb stuff like interpreting "make the div spin around" from some CSS/JS would probably work, as someone somewhere probably coded that similarly.

Re:TLDR explains what a piece of code does by SanderNL on Friday September 23, 2022 @04:41AM (#32949409)
GPT3 knows this is the fast inverse square root. Don't know about codex though, guess it does too.
Re:TLDR explains what a piece of code does by mrtksn on Friday September 23, 2022 @03:50AM (#32949128)
I'm always amazed by what AI can do but never been amazed by the actual output(amazed within the context that this is computer generated). Not just Copilot but any tool that has too much of intelligence of itself(Dall-e, Midjourneys etc) feels like this because it reminds me of a person with great talent for compositing stuff but doesn't know what they are doing.

AI generated papers that got published in prestigious journals situation all over again and again. At glance looks amazing but the machine definitely doesn't have any kind of intelligence and the output is actually worthless.

This AI stuff work really well when they do something very specific that is quickly inspectable by human, for example generating interpolated frames in videos or extending a pattern or detecting anomalies kind of stuff.

The moment it strays away from human control it fails amazingly well.

Re:TLDR explains what a piece of code does by daveguy on Thursday September 22, 2022 @07:49PM (#32946134)
You are grossly over-simplifying what this is doing. Nowhere does it say anything as simple as setting x to y. In nearly each case it takes the context of the variables into account and states the meaning of the function calls, not the meaning of the syntax.
Re:TLDR explains what a piece of code does by hn_throwaway_99 on Thursday September 22, 2022 @07:59PM (#32946213)
Yes, the examples I gave are gross over-simplifications. But look at the attached video. It literally just gives a 1-1 mapping of each code line to an English sentence, and that code is pretty trivial to understand in any case. I mean

    $data = file_get_contents(filename: 'php://input');
to

    "We're getting the raw request body"
I still argue that developers should be able to read the raw code like that faster than turning it into an English sentence. I'm not saying the text generation isn't extremely impressive, I just don't think it's that useful.
Re:TLDR explains what a piece of code does by wingerlang on Friday September 23, 2022 @04:18AM (#32949286)
Ironically your example would be a pretty great case for someone like me, who occasionally use PHP for fun but don't really use-use it.

    $data = file_get_contents(filename: 'php://input');
I would definitely have to google what this means, like why is it opening a file and how is 'php://input' a file?

    "We're getting the raw request body"
Is actually a good explanation.

So, someone new to a project, and maybe unfamiliar with the tech, might find this useful.

Re:TLDR explains what a piece of code does by nextaccountic on Thursday September 22, 2022 @11:20PM (#32947625)
> I just don't think it's that useful.

Even for experienced developers, it is useful when navigating a new codebase (where you don't know what each API call does) or even a new programming language (where a particular construct may be unfamiliar like Rust's if let). Well supposing the tool is accurate (incorrect results may make the tool useless or harmful)

But if you're discounting the usefulness for beginners I think this is a mistake. The experienced devs of tomorrow are the beginners of today.

Re:TLDR explains what a piece of code does by cdubzzz on Thursday September 22, 2022 @07:25PM (#32945944)
The tweet and video don’t seem to imply this _should_ be a comment.

I have been “learning to program” for 20+ years and would absolutely find this useful as a quick way to get basic information about a chunk of code I’m unfamiliar with.

Not that learning to read code isn’t important, just not always necessarily worth the time (:

Re:TLDR explains what a piece of code does by rk06 on Friday September 23, 2022 @05:06AM (#32949559)
My Rule of comments:

1. Write comment first, code later.

2. Tell the intent of code, not the instructions to achieve it

Re:TLDR explains what a piece of code does by kleiba on Friday September 23, 2022 @01:48AM (#32948491)
Agree. I find, what you usually want to understand is not the "what" or "how" but the "why", and that is quite a bit harder to automate than translating syntax into natural language statements.
Re:TLDR explains what a piece of code does by Quekid5 on Friday September 23, 2022 @04:25AM (#32949327)
Yeah, the 'why' often literally doesn't exist as information in the code anywhere, e.g. business rules, domain-specific knowledge, etc. If you're extremely lucky it might exist as 'why comments' :)

I do wonder if ML could be applied if you actually also train it on your particular (large) application where if might be able to 'cross-reference' domain knowledge present in commented code to other similar code. (But then you might want to just remove the pseudo-duplication anyway.)

Re:TLDR explains what a piece of code does by Gordonjcp on Friday September 23, 2022 @04:25AM (#32949326)
I caused a bit of an "incident" at a web dev company I worked at many many years ago by removing commit access from one of the "technical managers", whose hobby was removing every single comment he could find.

"But the code shouldn't need comments," he'd complain, "it should be obvious what it does otherwise it's just bad code!"

Yes, you dobber, it *is* obvious from the code, the *how* is obvious, but the why and the what might not be. The comments explain what it's doing stuff to and why, and in particular why you'd want that and why it's important. Disk space is free, so in a big long comment just write up what that particular bit of business logic is intended to achieve and what it expects as inputs and outputs.

or, TL;DR "DOCSTRINGS BITCH DO YOU SPEAK IT"

Re:TLDR explains what a piece of code does by more-coffee on Friday September 23, 2022 @06:12AM (#32949950)
I bet they also pulled out the "but the code will change and then the comments become invalid, or even gasp misleading"?
Re:TLDR explains what a piece of code does by Gordonjcp on Saturday September 24, 2022 @04:27AM (#32960730)
Absolutely, and could not be convinced that if the code and comments got out of sync then it was likely that the function name would no longer make sense, and that's when we get real trouble.

There were horror stories with that codebase, like index.php was set as the default error handler, started by immediately returning 200 OK before going anywhere near URL dispatching, and then displaying a page that said 404 despite returning 200 if it couldn't find the URL.

Re:TLDR explains what a piece of code does by alexvoda on Saturday September 24, 2022 @08:57AM (#32962136)
The only situation where i see an AI generating this type of comments to be useful would be deciphering an obfuscated C challenge program. Or maybe Perl.

But otherwise, I also want the Why not the What!

Re:TLDR explains what a piece of code does by aaaaaaaaaaab on Thursday September 22, 2022 @07:20PM (#32945920)
Yep. Nothing particularly mind-blowing about this. It's just a word-by-word translation of code into English. Heck, you don't even need GPT-3 to do this, except for some variety and grammatical correctness.
Re:TLDR explains what a piece of code does by danielvaughn on Thursday September 22, 2022 @08:01PM (#32946233)
What I like about it is that it could help me understand a new language. Sometimes it’s easy to follow what’s going on, but sometimes there are just odd language conventions that I’m not used to.
Re:TLDR explains what a piece of code does by xwowsersx on Thursday September 22, 2022 @07:23PM (#32945941)
Very much agree.