• philm@programming.dev
    link
    fedilink
    arrow-up
    4
    arrow-down
    2
    ·
    11 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
      arrow-up
      1
      ·
      11 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.