DEV Community

AI-generated explanations and documentation for JavaScript code

Lars Grammel on December 08, 2022

As a JavaScript developer, you know how challenging it can be to work with existing codebases. Often, the code is poorly documented, making it diff...

Read full post

Brad • Dec 10 '22

I think this is a great application for AI! Especially in situations where the code has gotten more convoluted over time.

But it also shouldn't be used as a hammer.

Comments that explain what the code does are redundant if the code is written clearly. The part that is missing, and the part the AI will also struggle with is the external context, or "why" the code is written the way it is.

Counter intuitively if you used this tech everywhere code quality could go down in a number situations.

Like many tools and patterns, there's always a best case and worse case.

Foxhoundn • Dec 11 '22

JSdoc comments are used for documentation (and also things like intellisense etc) - which means if you’re building a library you 10000000% need exceptional comments.

SeongKuk Han • Dec 14 '22

Wow...
These days, a lot of AI tech tools have been coming out.
I'm excited but at the same time, I'm also kind of scared.
They're coming into a real world.
Anyway, I should be going to talk about the tool with my team.
It's amazing

Marcelo Arias • Dec 11 '22

We're pretty close to AI generate a README from the source code.

SHIVANSH PATEL • Dec 8 '22

wow this is really awesome man ❤️

LedaHuerta • Dec 11 '22

I think it's a wonderful tool, it'll help me a lot, especially to describe utils or hooks. I develop some complex modules and sometimes I forgot what they do or how do certain things.

dannohh • Dec 9 '22

Very cool!

Ny Andry • Dec 8 '22

Game Changing.

Sean May • Dec 9 '22

I’m worried about the lack of context.
For reference, I recently needed to replace an argument. In order to do that, I needed to find the right argument in the calling class... which was created in the virtual override of the grandparent class, which was an implementation of the abstract great-grandparent, and that process only happened when triggered with a reaction to a global Rx stream triggering with the right payload, to dispatch that method.
Learning the name of the argument to use spanned ~8 files. My concern is that comments often obscure that kind of thing, because we are conditioned to read the English and not the code.

If the system, instead, could essentially do a reverse proxy through the files to tell me what I am looking for and where I will find it, in a deep inheritance codebase, that would be wonderful.

Lars Grammel • Dec 9 '22

Interesting case! From what I understand, you would have liked to know with what kinds of objects the function gets called, so you can more easily change the argument, right?

Sean May • Dec 9 '22 • Edited

I suppose the simplified case is this:

class Component {
  draw(x) {
    // this needs to be updated from taking one x to a list of xs, for business reasons
  }
}

class C extends class B {
  component;
  constructor(component) {
    super();
    this.component = component;
  }
  draw() {
    // this line needed to change to "x_list"
    this.component.draw(this.x);
  }
}

class B extends class A {
  handleAction(action) {
    if (this[action.type])
      this[action.type](action);
  }
}

class A extends Blueprint {
  constructor() {
    super();
    this.stream.subscribe(e => this.handleAction(e));
  }
  handleXs (action) {
    // note that these aren't defined members of the class
    // they're bolted on at runtime, if this fires
    this.x_list = action.data;
    this.x = action.data[0];
  }
}

class Blueprint {
  constructor () {
    this.stream = someGlobalStream;
  }
}

class Main {
  main () {
    window.someGlobalStream = new BehaviorSubject();
    const component = new Component();
    const consumer = new C(component);

    someGlobalStream.next({
      type: "handleXs",
      data: [1, 2, 3]
    });

    consumer.draw();
  }
}

this would be the closest to barebones that I think I could get, except that none of the instantiation or usage were in main; they were spread out in different places, the xs were loaded in a different service, located elsewhere, called by a different thing, and internally triggered the stream, the component was injected into C. Technically, this is Angular, so Component was used in the HTML template of C, but that's hard-mode. And all of these classes are, of course in different files in an mvc folder structure.

Lars Grammel • Dec 9 '22

Oh wow, thanks for sharing! Definitely a complex case. I will think about ways to solve this, but my current take is that automated tools are still a few years away from helping with something this complex.

Sean May • Dec 9 '22 • Edited

Yeah, I guess my concern is, if each of these files is already ~700 lines of code, and all of the comments explain what the line is doing, then you will have 1400 line files where nothing explains what the system is doing, and nobody will read past the English explaining the line... because humans like to optimize.

It would be handy, though, to have an IDE plugin, with tooltips/popups where you could eli5 an explanation and a simplified use case of any file / highlighted selection, like an MDN article on steroids. Wouldn't help me, here, but it could help people understand less complicated code, while keeping the source less cluttered.

Eva Lam • Dec 8 '22

Amazing ! This would really help me

teamradhq • Dec 13 '22

Neither of these features are very compelling and really just highlight VS Code's shortcoming more than anything. I mean, my IDE already makes docblocks generation trivial, just type /** and hit enter.

The main difference between IDE and AI is that with AI you have to delete all of the inaccurate text that it vomited on the screen vs providing accurate text.

To be fair, this is at least half generated by AI and is almost 100% inaccurate or redundant:

/**
 * Some semi-random text that was generated by a computer that 
 * you'll have to replace with accurate information.
 *
 * @param action A controller action.
 * @param message A message to display to the user.
 */
function doSomeControllerAction(
  action: ControllerAction, 
  message: string
): void

The action param is literally describing its type (very helpful AI).

The message param description is incorrect. It just so happens that a lot of existing implementation name things message if they intend to show it to the user. An intelligent being would have picked this up based on the use context.

The labour of producing accurate documentation manually is about the same, if not less, because you eliminate the cognitive overload of considering the accuracy of some randomness...

/**
 * Validate the `message` before calling the controller `action` with it.
 *
 * @param action A controller action that will be called with valid `message`.
 * @param message An activity that will be validated and then passed to the `action`.
 */
function doSomeControllerAction(
  action: ControllerAction, 
  message: string
): void

And the second gif doesn't explain the code. The tool is an interpreter. It doesn't explain the code, it translates it into plain English. This is exactly like somebody speaking to me in French and interpreter translating their statements. The role of the interpreter isn't to explain... The ability to understand still lies in the listener's ability to comprehend.

Go back to your AI generated "explanation" and see. Nothing in that generated text gives any context as to:

Why the code exists and was designed this way
Use cases where it would be beneficial
Issues with its current designs and improvements
How it relates to the broader application

If I asked you to explain some code to me I'd expect your answer to cover at least two of these points.

So yeah, while these example are cute, they're just another demonstration of how far away these tools are from being anywhere near as useful as the ones made by humans.

Tamschi • Dec 13 '22 • Edited

I have to second this, yes. The generated comments from the examples given in this post make the code worse by adding noise while providing little to no value (and I would reject this style of comment in contributions to my open-source projects).

I would especially caution against using tools like this if you're just starting out and looking to build a portfolio, also. This style of commenting is sometimes required in teaching environments specifically, and (if confused for manually written ones) highlights that you are an absolute beginner with little experience outside of that.

(It is fine to use the AI privately to help you understand the code, as long as you make sure that it is actually telling the truth each time. Doing so, you'll quickly gain the routine to read the code faster than you can read and verify the explanation in prose.)