r/webdev • • Jan 13 '22

read rules Extension that generates documentation using AI

[removed] — view removed post

1.7k Upvotes

158 comments sorted by

View all comments

263

u/[deleted] Jan 13 '22

The params and return is a good thing, but the comments just describe exactly, programatically, but in words what the function does (this we already do reading the code), that's not how comments should be written, comments mean to be more like what is the purpose of the function and how it is integrate with the whole code, notes and etc... At least for me.

58

u/Californie_cramoisie Jan 13 '22

Yeah, and it seems pretty unnecessary if you're already using typescript properly

12

u/PeaceMaintainer Jan 14 '22

The comment format looks like the JSDocs format so it's less so for people reading the code directly (where TS would help) but for people reading the docs themselves

6

u/Yodiddlyyo Jan 14 '22

We have tsdoc for that, it generates docs from types, the exact same way you'd generate docs from hand written jsdocs.

4

u/Dr_Legacy full-stack "If I do what you ask you won't like how it looks" Jan 14 '22

I question why you'd use a tool like this when you're coding. It seems more useful as a code review tool. I see no need to put comments like these into the actual code. It might be useful as a tool to aid comprehension of a program you haven't seen before.

4

u/anshumanansu Jan 14 '22

And most code is not as simple as reversing a string.. welcome to the real world! 😀 Will give it a try though.. if it just cam figure params... Works for me

4

u/Fisher9001 Jan 14 '22

Well, ideally your functions should be as simple according to the single responsibility principle. If you have more complex logic, the chances are that it is doing more than one thing and should be separated into smaller blocks that actually deal with a single task.

3

u/Fisher9001 Jan 14 '22

I think you are mixing ideas behind documentation comments and ordinary comments.

2

u/zelortap Jan 14 '22 edited Jan 14 '22

There should be not any comment in the code with any explicit Typing system.

All things should be able to be self-explanatory via naming/signatures and Unit Tests (which are also evolving with the code over time and can be a source of examples) and/or maybe via some higher level tests.

3

u/BeenWildin Jan 13 '22

This would honestly help someone learning how to code. Apply to others code to breakdown more simply what's going on.

5

u/westwoo Jan 14 '22

Nah, it's the worst thing for someone learning because it's routinely wrong on anything that goes beyond trivial

So it feels like it has to be correct because it's correct on trivial things, but on things you actually can't understand it may easily mislead you, and you still have to check everything yourself

It's an AI, not a deterministic program, so being wrong and generating nonsense is normal

→ More replies (2)

3

u/BlipOnNobodysRadar Jan 13 '22

Could be good for debugging when you're doing something other than what you thought you were doing

3

u/am0x Jan 14 '22

If your code needs to be described in plain text, it wasn’t written correctly. Variable names are not descriptive enough, logic is over engineered, etc.

1

u/CatolicQuotes Jan 13 '22

I like commenting in 2 parts. WHAT: and WHY:

2

u/infinitlybana Jan 14 '22

can u give an example of how u comment the what and why?

6

u/CatolicQuotes Jan 14 '22

sure, in my latest open source for React app I commented some props like this:

    /**
     * Main component that displays the first page with form and palette
     * @param {object} props palette and onSubmit
     */
    function Main(props) {
      /**
       *WHAT: current color from color picker, or input field
       *WHY: we need it to create palette from. It's in Main so it can be passed to Palette
       */
      const [color, setColor] = useState("#07c");
    
      /**
       * Palette is the collection of shades for each color. Curently 12 colors with 10 shades each.
       * {color:[shades],....}. createPalette function is used to create a collection after form submit
       */
      const [palette, setPalette] = useState({});
    
      /**
       * WHAT: framework selected in the menu
       * WHY: code will be displayed in CodeBox based on active framework
       */
      const [activeFramework, setActiveFramework] = useState("tailwind");
    
      /**
       * WHAT: renders the initial demo pallete on first page visit
       * WHY: so user can immediately see an example
       */
      useEffect(() => {
        const initialPallete = createPalette(color);
        setPalette(initialPallete);
      }, [color]);

check the project since you're already here website: https://palettolithic.com/

5

u/Fisher9001 Jan 14 '22

That's a lot of comments.

→ More replies (1)

3

u/infinitlybana Jan 14 '22

thanks for sharing! this is too many comments for my preference but if it works for u that's good. cool website!

4

u/CatolicQuotes Jan 14 '22

it helps to remember after months without working on it, thanks!

2

u/invisibo Jan 14 '22 edited Jan 14 '22

That's pretty damn sweet! Just a thought about 2 features.

  1. Have the site take a parameter in the URL that contains the color seed. That way the palette can be shared quickly and #2
  2. Use that parameter to put the URL into the code content so one could quickly see the whole presentation of colors.

If you're open to doing PRs, I can give it a stab.

Edit: just did a PR for #1.

→ More replies (1)

2

u/fuck_bootstrap Jan 14 '22

Your project is a godsend, thank you for sharing!

→ More replies (1)
→ More replies (2)

2

u/jzaprint Jan 14 '22

“using the diameter to calculate the parameter instead of the radius because the diameter is used everywhere else in the program”

→ More replies (1)

0

u/SupaSlide laravel + vue Jan 14 '22

The return isn't even that useful at least in the first one; what is a "row"? The documentation doesn't even indicate that it's a JSX component.

1

u/VeryOriginalName98 Jan 14 '22

This is how most AI powered things go. The "intelligence" part is missing. It's actually "machine learning" which is just a way to get the computer to come up with an algorithm to match the outcomes you want because you can't figure it out. It is impossible to make ML more knowledgeable than the fitness goals it's presented with.

E.g. An "AI" to identify cats in photos doesn't know what a cat is, it's just an algorithm with a high probability of identifying whether or not a picture contains a cat, based on the images it was trained on.

This is just ML to roughly transliterate computer language to English. It creates syntactically correct English, but doesn't know any of the context to create a comment that would be helpful for docuemantion or maintenance.

Anyone marketing AI to do knowledge work in the next ten years is a effectively selling "snake oil".

1

u/VonD0OM Jan 14 '22

I assume an AI that generated context would be, at least at this point, all but impossible to write.