I know there are documentation generators (like JSDoc in JavaScript) where you can literally write documentation in your code and have a documentation site auto-generated at each deployment. There’s definitely mixed views on this though
Comment on How to properly document code?
CookieOfFortune@lemmy.world 11 months ago
Your code should generally be self documenting: Have variable and method names that make sense.
Use comments when you need to explain something that might not be obvious to someone reading the code.
Also have documentation for your APIs: The interfaces between your components.
silas@programming.dev 11 months ago
CookieOfFortune@lemmy.world 11 months ago
To my knowledge that just formats existing comments. With LLMs you could probably do 95% of the actual commenting.
superb@lemmy.blahaj.zone 11 months ago
Useful comments should provide context or information not already available in the code. There is no LLM that can generate good comments from the source alone
silas@programming.dev 11 months ago
CookieOfFortune@lemmy.world 11 months ago
Why wouldn’t it be able to? It can link similar code structure to data in its training set. Maybe the ones that aren’t at that level but it’s hardly a stretch to make these inferences. Most of the code you write is hardly novel.
Aurenkin@sh.itjust.works 11 months ago
One interesting thing I read was that commenting code can be considered a code smell. It doesn’t mean it’s bad, it just means if you find yourself having to do it you should ask yourself if there’s a better way to write the code so the comment isn’t needed. Mostly you can but sometimes you can’t.
Agree with you though, generally people should be able to understand what’s going on by reading your code and tests.
MajorHavoc@lemmy.world 11 months ago
Great points. I’m a huge advocate for adding comments liberally, and then treating them as a code smell after.
During my team’s code reviews, anything that gets a comment invariably raises a “could we improve this so the comment isn’t need?” conversation.
Our solution is often an added test, because the comment was there to warn future developers not to make the same mistake we did.