Comment by slotrans

9 months ago

> I will completely forget why I wrote it that way.

This is the main reason for comments. The code can never tell you "why".

Code is inherently about "what" and "how". The "why" must be expressed in prose.

8 comments

slotrans

Reply
Cthulhu_  9 months ago

And the described use case - USB stuff with very specific exception - makes a strong case for literate programming, that is, more prose than code.

  • lompad  9 months ago

    Does everything have to be pushed into a structure-prescribing set of rules?

    Can't we just say "comments are useful here" without trying to make it into a case for $methodology?

    • kragen  9 months ago

      Literate programming isn't a structure-prescribing set of rules or a methodology. It's just making the prose primary and the code secondary.

ninetyninenine  9 months ago

Why not put the prose in the name of the function?

  • SAI_Peregrinus  9 months ago

    Function names are limited. E.g. can't provide a circuit diagram of what you're controlling in a function name. But you can do that in a comment (either with ASCII art or an image link).

    • ricree  9 months ago

      In addition to that, if the Why ever changes (maybe the issue was in an external dependency that finally got patched), you'd have to update the name or else leave it incorrect. Mildly annoying if just in one codebase, but a needlessly breaking change if that function is exported.