79
Self-documenting Code (lackofimagination.org)
you are viewing a single comment's thread
view the rest of the comments
[-] humblebun@sh.itjust.works 1 points 1 day ago

Code should be generated from documentation imo

[-] verstra@programming.dev 4 points 1 day ago

Documentation should be generated from code imo

[-] Zagorath@aussie.zone 5 points 1 day ago

If the doco we're talking about is specifically an API reference, then the documentation should be written first. Generate code stubs (can be as little as an interface, or include some basic actual code such as validating required properties are included, if you can get that code working purely with a generated template). Then write your actual functional implementation implementing those stubs.

That way you can regenerate when you change the doco without overriding your implementation, but you are still forced to think about the user (as in the programmer implementing your API) experience first and foremost, rather than the often more haphazard result you can get if you write code first.

For example, if writing a web API, write documentation in something like OpenAPI and generate stubs using Swagger.

[-] humblebun@sh.itjust.works 4 points 1 day ago

Same for drivers. Generate headers from documentation and distribute it you fucking morons

[-] Zagorath@aussie.zone 3 points 1 day ago

Yup absolutely. I mentioned web APIs because that's what I've got the most experience with, but .h files, class library public interfaces, and any other time users who are not the implementor of the functionality might want to call it, the code they'll be interacting with should be tailored to be good to interact with.

[-] key@lemmy.keychat.org 5 points 1 day ago

Code should be generated from documentation generated from code

[-] svetlyak40wt@fosstodon.org 2 points 1 day ago

@key @verstra documentation should be generated from neuro-waves, generated from a brainstorm.

[-] humblebun@sh.itjust.works 3 points 1 day ago
[-] 0x0@programming.dev 5 points 1 day ago

Could be .jar too.

[-] Deckweiss@lemmy.world 5 points 1 day ago

Just run both in a loop until it reaches a state of equilibrium.

[-] humblebun@sh.itjust.works 2 points 1 day ago

Or use LLM to generate the doc from all sources you have. Foolproof 100%

[-] nous@programming.dev 1 points 1 day ago

Better yet, use LLM to generate the docs - then use it again to generate the code form the docs. WCPGW

[-] humblebun@sh.itjust.works 3 points 1 day ago

You sound like a CEO. Do you have a spare CTO role?

load more comments (8 replies)
this post was submitted on 21 Oct 2024
79 points (85.6% liked)

Programming

17241 readers
262 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Rules

  • Follow the programming.dev instance rules
  • Keep content related to programming in some way
  • If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities !webdev@programming.dev



founded 1 year ago
MODERATORS