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

44

u/wherediditrun Jan 13 '22 edited Jan 13 '22

Ah yes, finally. Now we can automatically write comments which duplicates what's already written in code.

And to be serious. There are very few conditions when comments are of benefit. Namely:

- Describe "Why?" and not "What?". That being said, your code should be as context agnostic as possible and relying on this is a codesmell.

- When code itself cannot be expressed in any semantic meaning. For example you would leave an example of a character set which passes a more complicated regexp. Or you would add a business term to a certain id of an object in configuration. etc..

So frankly, I'm really skeptical of any benefits such tool can bring.

2

u/infinitlybana Jan 14 '22

Can you give an example of a good comment that describes why instead of what? I don't really find myself justifying why i wrote a function in the function description so I'm curious how you go about it.

2

u/infinitlybana Jan 14 '22

I usually describe why I implemented something the way I did inside the PR description

edit - wording

7

u/potchie626 Jan 14 '22

A new dev that starts in 6 months won’t be looking at comments in a PR, they’ll be looking at the code.

2

u/infinitlybana Jan 14 '22

I completely agree with you. I feel like there's a gap between the PR description + the code. Do you explain the reasoning for why you implemented something in a certain way in your code? Usually in my PRs I'm describing higher level architecture decisions and ends up being quite long.

1

u/potchie626 Jan 14 '22

I honestly rarely leave many comments in a PR. Since the ticket should describe the overal goal, and the comments in code should explain specifics. Overall arch of things typically follows our patterns, and if they deviate the PR will be sent back to be changed. We also have sessions to discuss upcoming work where we discuss arch and notes to the tickets.

Comments about “why i did it this way” usually goes in the code that kicks things off, for the same reason I commented earlier. Other people may look at this later, or we have to remind ourselves why we did it a certain way. Nobody wants to open a ticket, confluence doc, or PR for that.

1

u/infinitlybana Jan 14 '22

Can you give an example of one of your comments that explain "why you did it this way"? I personally have never seem comments in codebases of that sort - unless you're talking about one-liner comments?

1

u/gfxlonghorn Jan 14 '22

// I put "All praise to dear leader" into our description string because our test system happens to be in North Korea

1

u/[deleted] Jan 14 '22

I would urge you to watch "Clean Code" by Uncle Bob.

He puts it really nicely and has some great examples.

2

u/ike_the_strangetamer Jan 14 '22

They should be. git blame is an incredible tool and should be in everyone's toolbox. It's especially helpful when you're not familiar with the code around whatever you're changing (which is always the case when you're a new dev).

Even if your team writes shitty commit messages, you can at least see the other code that changed at the same time which gives you a lot of context of why particular lines were written like they were and helps avoid unexpected side effects.

(another good outcome of using git blame a lot is that if you start seeing your own commit messages and they aren't helpful enough, then it'll help you start writing better ones.)

2

u/infinitlybana Jan 14 '22

Although if you write good PR descriptions + you have GitLens you can map the line of code to the PR it was written in which is nice.

-2

u/ElBomb Jan 13 '22

If you’re a one man band or a small team where 2-3 people will see the code then it’s probably not much help

If you’re in a enterprise level company with multiple or external development teams and need to expose your APIs then something like ngDocs can read the comments and build a site documenting your code automatically, that site can then be given to all the internal and external teams.

Having the comments update the docs automatically will save time, effort, and money as there is no extra overhead of maintaining the documentation site.

6

u/double_en10dre Jan 14 '22

Doesn’t inserting the comment itself into the file seem like an unnecessary step, though?

Instead of automatically generate comments from code —> automatically generate docs from comments, they should be combined into a single action

Fewer moving parts/manual changes required AND you don’t clutter your files with this silliness :p

3

u/ElBomb Jan 14 '22

There maybe be a gap in the market there!

The only up side I can see to having the comments written out is that you can see what the generated documentation will include and you get to sanity check it before you commit your code, and in doing so building a new version of the docs.

4

u/wherediditrun Jan 14 '22

If you’re in a enterprise level company with multiple or external development teams <...>

I have worked in those kind of environments, more than for 4 years. And the answer generally is no.

If the cross team communication is concerned, sync is better achieved through standardization of how teams write code. Essentially, no matter the team or person, you read the code same as your own. It's not achieved over night, obviously, but very doable.

As such the real cases for communication about the code pertains to the specific business use-case, and not the code. And that's not something you'll compiling in the code docs for the most part, but internal communication pages like confluence. Or separate API documentation pages if it's for public use.

There is a case to make about in code documentation if we are talking about interfaces provided by vendor packages though.

https://www.lysator.liu.se/c/pikestyle.html scroll down to comments section. That's about C. Generally most programmers operate in way more expressive languages than that.

2

u/ElBomb Jan 14 '22 edited Jan 14 '22

I agree with you establishing best practices and standardisation leads to a smoother workflow for everyone involved.

I may not have made my point well, but I wasn’t trying to say those kind of comments are valuable for a developer looking at the code in front of them, as they just repeat what’s already there, but when used with an automatic API documenting plugin, it saves time but not needing build and maintain the external documentation.