4 ms·

There is an important case for comments that neither of them touched on. Sometimes you are dealing with bugs or counterintuitive processes beyond your control.

There is an important case for comments that neither of them touched on. Sometimes you are dealing with bugs or counterintuitive processes beyond your control. For example, I am writing some driver software for a USB device right now. It is so easy to get the device into a bad state, even when staying within the documented protocol. Every time I implement a workaround, or figure out exactly how the device expects a message to appear, I put in a comment to document it. Otherwise, when (inevitably) the code needs to have features added, or refactoring, I will completely forget why I wrote it that way. The prime number example is a self-contained, deterministic algorithm. While I did find it far easier to parse with comments, I could still spend the time to understand it without them. In my USB device driver, no amount of review without comments would tell another person why I wrote the sequence of commands a certain way, or what timings are important. The only way around that would be with stupid method names like `requestSerialNumberButDontCallThisAfterSettingDisplayData` or `sendDisplayDataButDontCallTwiceWithin100Ms`.

mbo 2y ago
While I am not a Uncle Bob-style "no comments"er I do love a ridiculous method name. I pay very close attention to that method and the context in which it is called because, well, it must be doing something very weird to deserve a name length like that.
- tikhonj 2y ago
  There are a few Haskell functions with names like reallyUnsafePtrEquality# or accursedUnutterablePerformIO, and you know something interesting is going on :P
- hakunin 2y ago
  That’s exactly why you should save that length only for a method that’s indeed doing something weird. If every method is long, the codebase turns into noise. (IOW I agree)
  - ninetyninenine 2y ago
    This doesn’t happen in reality. Your program does so many things that practically speaking short names work for a lot of functions in the program. It’s like English. There are big words and there are small words and usually to communicate a combination of big and small words are used. Nobody practically communicates with big words. A long function name only pops up when needed.
    - hakunin 2y ago
      It happened in the article we’re discussing, and seems to be something Robert advocates for.
      - ninetyninenine 2y ago
        Happened in a contrived example.
        kristiandupont 2y ago
        Contrived perhaps, but it was an example that was supposed to demonstrate the benefits to those long names. In my opinion, it did the opposite.
  - Pxtl 2y ago
    I used to work this way, but I found that every non-trivial method involves edge-cases and workarounds documenting them the method name destroyed readability.
    - hakunin 2y ago
      The only point I was making is that short name signals that nothing unusual is going on, and long name signals that you have to pay extra attention. I never suggest to replace a comment with a long name. Here's my 4 reasons to leave a comment: https://max.engineer/reasons-to-leave-comment https://max.engineer/reasons-to-leave-comment Comments are crucial for "why", and additional context. Name shouldn't go beyond "what". More on that here: https://max.engineer/maintainable-code https://max.engineer/maintainable-code (Check the "What" section that focuses on naming).
zbentley 2y ago
> The only way around that would be with stupid method names Yep. Method names make terrible comments. No spaces, hard to visually parse, and that's before acronyms and ambiguity enter the conversation. As the person who often writes borderline-essay-length comment blocks explaining particularly spooky behaviors or things to keep in mind when dealing with a piece of counterintuitive/sensitive/scary code, my reason for mega-commenting is even simpler: all the stuff I put in comments should absolutely instead live in adjacent documentation (or ADRs, troubleshooting logs, runbooks, etc). When I put it in those places, people do not read it, and then they do the wrong things with the code. When I put it in comments, they read it, as evidenced by the rate of "that bug caused by updating the scary code in the wrong way happened again"-type events dropping to zero. It's easier to fix comment blocks than it is to fix engineers.
- rswail 2y ago
  > Yep. Method names make terrible comments. No spaces, hard to visually parse, and that's before acronyms and ambiguity enter the conversation. Which is why snake_case or kebab-case (if the language allows it) is much better than PascalCase or camelCase. Even worse when camelCase enters into JSON because people want to automate the serde but are too lazy to make the actual interface (the JSON Schema) easy to read and debug.
- colddevil 2y ago
  Upvote for mentioning ADRs! ;) I really like the approach and as other comments already mentioned, this is a nice way to capture the "why" of specific decisions that go beyond the "how" in the code. Here is a good starting point for people not familiar with ADRs: - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions https://cognitect.com/blog/2011/11/15/documenting-architectu... - https://adr.github.io/ https://adr.github.io/
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 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 2y 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 2y 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 2y ago
  Why not put the prose in the name of the function?
  - SAI_Peregrinus 2y 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).
    - ninetyninenine 2y ago
      Agreed. 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.
Mawr 2y ago
Sounds like you should instead be making these invalid states unrepresentable by encoding them in types and/or adding assertions. Especially if you're exposing them as interfaces, as your example function names would imply.
- kragen 2y ago
  They're invalid states inside the USB device, not inside the driver code. So nothing you do to the driver code can make them unrepresentable. The best you can do is avoid frobbing the device in the problematic ways.
- marcosdumay 2y ago
  The GP is making those invalid states unreachable by writing a device driver.
deleted 2y ago
[deleted]
bch 2y ago
> For example, I am writing some driver software for a USB device right now. It is so easy to get the device into a bad state, even when staying within the documented protocol. Every time I implement a workaround, or figure out exactly how the device expects a message to appear, I put in a comment to document it. Otherwise, when (inevitably) the code needs to have features added, or refactoring, I will completely forget why I wrote it that way. I believe in general there is a case for this (your case sounds like a perfect candidate). The implementation of Dtrace is another example[0] full of good description, including ASCII diagrams (aside: a case for knowing a bit of Emacs (though I'm sure vim has diagramming too, which I would know if I pulled myself out of nvi long enough to find out)). [0] https://github.com/opendtrace/opendtrace/blob/master/lib/libdtrace/common/dt_consume.c https://github.com/opendtrace/opendtrace/blob/master/lib/lib...
kragen 2y ago
Have you thought about distilling your hard-earned information about the device's behavior into a simulator for the device you could test your code against?
ninetyninenine 2y ago
I don’t see anything wrong with those names. A bit hard to parse but the name moves with the function call while a comment does not. It’s annoying to look at but when you actually read the function you know what it does. A more elegantly named function is less annoying to read but less informative and doesn’t provide critical information. The name just looks ugly. But it’s like people have this ocd need to make things elegant when elegance is actually detrimental to the user. Can you actually give a legitimate reason why a method name like that is stupid other then its “hard to parse”. Like another user said… use snake case if you want to make it easier.
klysm 2y ago
Encoding temporal dependencies (or exclusions) between methods is hard. You can get partially there by using something like a typestate pattern (common in rust).

mbo 2y ago

While I am not a Uncle Bob-style "no comments"er I do love a ridiculous method name. I pay very close attention to that method and the context in which it is called because, well, it must be doing something very weird to deserve a name length like that.

tikhonj 2y ago
There are a few Haskell functions with names like reallyUnsafePtrEquality# or accursedUnutterablePerformIO, and you know something interesting is going on :P
hakunin 2y ago
That’s exactly why you should save that length only for a method that’s indeed doing something weird. If every method is long, the codebase turns into noise. (IOW I agree)
- ninetyninenine 2y ago
  This doesn’t happen in reality. Your program does so many things that practically speaking short names work for a lot of functions in the program. It’s like English. There are big words and there are small words and usually to communicate a combination of big and small words are used. Nobody practically communicates with big words. A long function name only pops up when needed.
  - hakunin 2y ago
    It happened in the article we’re discussing, and seems to be something Robert advocates for.
    - ninetyninenine 2y ago
      Happened in a contrived example.
      - kristiandupont 2y ago
        Contrived perhaps, but it was an example that was supposed to demonstrate the benefits to those long names. In my opinion, it did the opposite.
- Pxtl 2y ago
  I used to work this way, but I found that every non-trivial method involves edge-cases and workarounds documenting them the method name destroyed readability.
  - hakunin 2y ago
    The only point I was making is that short name signals that nothing unusual is going on, and long name signals that you have to pay extra attention. I never suggest to replace a comment with a long name. Here's my 4 reasons to leave a comment: https://max.engineer/reasons-to-leave-comment https://max.engineer/reasons-to-leave-comment Comments are crucial for "why", and additional context. Name shouldn't go beyond "what". More on that here: https://max.engineer/maintainable-code https://max.engineer/maintainable-code (Check the "What" section that focuses on naming).

zbentley 2y ago

> The only way around that would be with stupid method names Yep. Method names make terrible comments. No spaces, hard to visually parse, and that's before acronyms and ambiguity enter the conversation. As the person who often writes borderline-essay-length comment blocks explaining particularly spooky behaviors or things to keep in mind when dealing with a piece of counterintuitive/sensitive/scary code, my reason for mega-commenting is even simpler: all the stuff I put in comments should absolutely instead live in adjacent documentation (or ADRs, troubleshooting logs, runbooks, etc). When I put it in those places, people do not read it, and then they do the wrong things with the code. When I put it in comments, they read it, as evidenced by the rate of "that bug caused by updating the scary code in the wrong way happened again"-type events dropping to zero. It's easier to fix comment blocks than it is to fix engineers.

rswail 2y ago
> Yep. Method names make terrible comments. No spaces, hard to visually parse, and that's before acronyms and ambiguity enter the conversation. Which is why snake_case or kebab-case (if the language allows it) is much better than PascalCase or camelCase. Even worse when camelCase enters into JSON because people want to automate the serde but are too lazy to make the actual interface (the JSON Schema) easy to read and debug.
colddevil 2y ago
Upvote for mentioning ADRs! ;) I really like the approach and as other comments already mentioned, this is a nice way to capture the "why" of specific decisions that go beyond the "how" in the code. Here is a good starting point for people not familiar with ADRs: - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions https://cognitect.com/blog/2011/11/15/documenting-architectu... - https://adr.github.io/ https://adr.github.io/

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 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 2y 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 2y 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 2y ago
Why not put the prose in the name of the function?
- SAI_Peregrinus 2y 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).
  - ninetyninenine 2y ago
    Agreed. 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.

Mawr 2y ago

Sounds like you should instead be making these invalid states unrepresentable by encoding them in types and/or adding assertions. Especially if you're exposing them as interfaces, as your example function names would imply.

kragen 2y ago
They're invalid states inside the USB device, not inside the driver code. So nothing you do to the driver code can make them unrepresentable. The best you can do is avoid frobbing the device in the problematic ways.
marcosdumay 2y ago
The GP is making those invalid states unreachable by writing a device driver.

deleted 2y ago

[deleted]

bch 2y ago

> For example, I am writing some driver software for a USB device right now. It is so easy to get the device into a bad state, even when staying within the documented protocol. Every time I implement a workaround, or figure out exactly how the device expects a message to appear, I put in a comment to document it. Otherwise, when (inevitably) the code needs to have features added, or refactoring, I will completely forget why I wrote it that way. I believe in general there is a case for this (your case sounds like a perfect candidate). The implementation of Dtrace is another example[0] full of good description, including ASCII diagrams (aside: a case for knowing a bit of Emacs (though I'm sure vim has diagramming too, which I would know if I pulled myself out of nvi long enough to find out)). [0] https://github.com/opendtrace/opendtrace/blob/master/lib/libdtrace/common/dt_consume.c https://github.com/opendtrace/opendtrace/blob/master/lib/lib...

kragen 2y ago

Have you thought about distilling your hard-earned information about the device's behavior into a simulator for the device you could test your code against?

ninetyninenine 2y ago

I don’t see anything wrong with those names. A bit hard to parse but the name moves with the function call while a comment does not. It’s annoying to look at but when you actually read the function you know what it does. A more elegantly named function is less annoying to read but less informative and doesn’t provide critical information. The name just looks ugly. But it’s like people have this ocd need to make things elegant when elegance is actually detrimental to the user. Can you actually give a legitimate reason why a method name like that is stupid other then its “hard to parse”. Like another user said… use snake case if you want to make it easier.

klysm 2y ago

Encoding temporal dependencies (or exclusions) between methods is hard. You can get partially there by using something like a typestate pattern (common in rust).