• humblebun
    link
    fedilink
    English
    arrow-up
    3
    arrow-down
    3
    ·
    2 months ago

    Code should be generated from documentation imo

      • Zagorath@aussie.zone
        link
        fedilink
        arrow-up
        5
        ·
        2 months 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
          link
          fedilink
          English
          arrow-up
          4
          ·
          2 months ago

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

          • Zagorath@aussie.zone
            link
            fedilink
            English
            arrow-up
            3
            ·
            2 months 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.