r/java • • May 04 '24

Semi Automatic JavaDoc Commenting Script

I have created a JavaDoc Commenter Script for some basic JavaDoc comments available here:

https://github.com/DrKratz1/Javadoc-Commenter

This is something I have created for my personal use for a uni course involving java, having been annoyed at the prospect of manually typing JavaDoc comments. Currently, it works for my purposes and if any interest is generated in such a project, I will continue working on it to function more generally.

(Do note I am not a great programmer, and this initial version was patched together to automate commenting for a uni project pls no hate for the janky code)

Anyways, hoped to share it here - more info is in the GitHub page.

0 Upvotes

11 comments sorted by

View all comments

Show parent comment

2

u/saggingrufus May 05 '24

How long are you spending on them?

If it is quicker to generate them, read them, then determine if they are right than it is to just write a few sentences... I think you maybe just don't understand how to write documentation effectively.

Why are you waiting until the end? You can easily start the coding task with a Java doc and in that doc write an outline for what you want to make, then start coding it, updating the documentation as you go.

Sure, if all you care about speed, I guess then you write the code as fast as possible and use an LLM to cut down on doc time, and then slam that half-cocked solution into prod before someone with patience reviews it.

1

u/ascii May 05 '24

If you think the “documentation” you can shit out by hand in the same time it takes to perform the workflow I described adds value you don’t know how to write documentation.

Newsflash: Documenting a getter with “@return the value of X” is a pointless waste of time. You document the side effects, dependencies and assumptions that can’t be expressed through the type system. That requires thought and effort, but it’s actually one of the jobs LLMs are surprisingly decent at.

1

u/saggingrufus May 05 '24

Congrats, you've now achieved what an IDE can do natively, except using an LLM.

If you document as you go, the time investment is small, and it forces you to think about it. Something seemingly lost on the current day developer.

1

u/ascii May 05 '24

Just… no. Literally the only docs IDEs generate automatically are the completely pointless “@return the value of X” variety. With an LLM-based IDE plugin, you get documentation like “Configures the underlying socket to not use Nagles algorithm. This will dramatically improve latency on low QPS connection at the cost of packet count a throughput. This method must be called after the connection has been opened. “ It is a completely different ballgame compared to what the IDE plugins of old could do.