cross-posted from: https://lemmy.bestiver.se/post/919071
You must log in or register to comment.
- 4 months
This has been the norm for literally decades. Doxygen was doing it in 1997 and I’m sure it wasn’t the first.
- 4 months
AI agents are becoming your biggest API consumers, and they can’t always DM other teams. If you want to be productive with AI, if you want your codebase to be a place where agents can actually work, you need to think of your codebase as an application that the agent is interacting with.
So what you’re saying is: mis-type everything! 👉😉👉
- 4 months
Yeaaaah, they may be the biggest consumers, but they’re not users and they’re not terribly useful to users. I’m not changing everything around to make some LLM spit out more easily believed misinformation.
- ell1e@leminal.spaceEnglish4 months
Seems like a solution would be 1. update docs and 2. don’t use LLMs to code.
- 4 months
Uhm, ship both. Most type systems are not expressive enough to 100% explain the correct use of an API.
- codeinabox@programming.devEnglish4 months
Regardless of what the author says about AI, they are bang on with this point:
You have the truth (your code), and then you have a human-written description of that truth (your docs). Every time you update the code, someone has to remember to update the description. They won’t. Not because they’re lazy, but because they’re shipping features, fixing bugs, responding to incidents. Documentation updates don’t page anyone at 3am.
A previous project I worked on we had a manually maintained Swagger document, which was the source of truth for the API, and kept in sync with the code. However no one kept it in sync, except for when I reminded them to do so.
Based on that and other past experiences, I think it’s easier for the code to be the source of truth, and use that to generate your API documentation.
- 4 months
Every time you update the code, someone has to remember to update the description. They won’t.
I get there are some exceptions where devs don’t have access to the docs, but I read this more like “Every time I update the code, I have to remember to update the description. I won’t.” Which, fair, but that’s the author’s problem. Writing docs is part of the job, table stakes stuff.
- MagicShel@lemmy.zipEnglish4 months
You can also use the OpenAPI generator to turn a well-formed Swagger document into code. I’ve used it before. I didn’t hate it.
The generated controllers have a lot of boilerplate (I want to say 5 classes per controller), but it does guarantee the code is in sync with the documentation.
That being said, fuck manually maintaining swagger documents. It’s the worst of all possible works.
- 4 months
I mostly agree with your statement and I’m just nitpicking, but that document is not a source of truth if it has to be updated after the fact, it’s a reference.
- ell1e@leminal.spaceEnglish4 months
There are solutions to this like having a doc comment right next to the function which is picked up by some API generator. Then it’s easier to keep in sync. That can work well even in languages without explicit parameter types.
Of course it won’t help LLMs as much, but I personally don’t mind that.