4 ms·
> 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" a
by slotrans 2y 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.
- Cthulhu_ 2y agoAnd the described use case - USB stuff with very specific exception - makes a strong case for literate programming, that is, more prose than code.
- lompad 2y agoDoes 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 2y agoLiterate programming isn't a structure-prescribing set of rules or a methodology. It's just making the prose primary and the code secondary.
- ninetyninenine 2y agoWhy not put the prose in the name of the function?
- SAI_Peregrinus 2y agoFunction 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).
- ninetyninenine 2y agoAgreed. So why not stuff as much as possible into the name before resorting to a comment? Prose looks ugly as a name but the utility is not diminished.
- SAI_Peregrinus 2y agoThat embeds the "why" into your API. If it ever changes, the function no longer serves as an abstraction over that underlying reason & changing the function name breaks your API. That's not to say embed nothing into the names. I'm quite fond of the "Long Names are Long" blog post[1]: names need to clearly refer to what the named thing does, and precise enough to exclude stuff it doesn't do. Names can certainly get too short, e.g. the C "sprint fast" function `sprintf` is probably too short to be easily understood. [1] https://journal.stuffwithstuff.com/2016/06/16/long-names-are-long/ https://journal.stuffwithstuff.com/2016/06/16/long-names-are...
- ricree 2y agoIn 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.