• @potustheplant@feddit.nl
    link
    fedilink
    347 months ago

    That’s like saying a book’s synopsis shouldn’t exist because you can just read the whole book. Sometimes comments can save you a lot of time and point you in the right direction.

    • @philm@programming.dev
      link
      fedilink
      47 months ago

      Nah, it’s not, code is modular (IME should be kinda tree-structured), a book is linear.

      So the API should be in your analogy the synopsis. And I haven’t said, that there shouldn’t be any comments. E.g. doc-comments above functions, explaining the use-cases and showing examples are good practice.

      • @potustheplant@feddit.nl
        link
        fedilink
        17 months ago

        Books can be modular as well (ever heard of “Rayuela” by Cortazar?) But that’s beside the point. The analogy is fine and it works.