4 ms·

Literate programming sounds nice... but then I read all those people outlining the horrors of too many comments. I have trouble reconciling these approaches.

• taeric 8y ago
  The comments of a literate program are not just comments scattered throughout the program. Not are they just an index of what is in a program. Rather, they build a narrative. It is literally explaining the program. In full.
  • jf 8y ago
    > It is literally explaining the program. In full. Precisely. Here are real world examples of this: A program that implements on-the-fly encoding of images into SSTV audio files (3620 words): https://github.com/jpf/dial-a-cat#1-855-meow-jam-sending-cat-pictures-over-the-phone-via-space-age-technology https://github.com/jpf/dial-a-cat#1-855-meow-jam-sending-cat... An example SCIM server (7966 words): https://github.com/joelfranusic-okta/okta-scim-beta#welcome-to-the-okta-scim-beta https://github.com/joelfranusic-okta/okta-scim-beta#welcome-... An example OIDC "RP" implementation (7731 words): https://github.com/joelfranusic-okta/okta-scim-beta#welcome-to-the-okta-scim-beta https://github.com/joelfranusic-okta/okta-scim-beta#welcome-...
    • your-nanny 8y ago
      I'm sorry, but I think I don't get it. all those examples consist of regular old sparsely commented code files with really thouroughly written READMEs, written in org. how is that special or any different than Readme driven development?
      • jf 8y ago
        The README and the code always stay in sync. An update in once place changes both the code and the documentation.