4 ms·

Shed a tear for how little our industry values conciseness, and then consider: # Call foo_bar only on the 4th loop iteration to handle the weirdness of calcu

Shed a tear for how little our industry values conciseness, and then consider: # Call foo_bar only on the 4th loop iteration to handle the weirdness of calculating taxes for California. (I've just joined a company where everyone's constantly writing giant docs, and no one seems to grok the idea of a "living doc" that gets edited and refined. I think it's slowly making me allergic to verbosity.)

mbesto 4y ago
I get your point (yours is written much better), but having comments that feel more like inner monologue is actually a good thing.
billforsternz 4y ago
These are both terrible comments (IMHO) because they tantalise the reader (the coder knew why they did this mysterious thing!) but don't actually really explain why this is necessary or how this mysterious thing actually addresses the messy reality involved. The problem might just be that it's an unrealistic example.
- nydev 4y ago
  Could be elaborated but this is 1000x better than nothing. The reader can look up what's unusual with enough hints from this comment.
- mbesto 4y ago
  If you're going to call something terrible, it's a little more productive to offer a suggestion for something better.
  - billforsternz 4y ago
    Okay instead of # Call foo_bar only on the 4th loop iteration to handle the weirdness of calculating taxes for California # Call foo_bar only on the 4th iteration because in California widget tax # (1st iteration) doesn't apply at all, foo tax (2nd iter.) only applies # for B2B transactions (this is not one), bar tax (3rd iter.) only applies # for alcohol and this subsystem is not called for alcohol sales. But VAT # (4th iteration) does apply.
    - billforsternz 4y ago
      HN hasn't respected my line breaks.
      - azemetre 4y ago
        I believe you need to have multiple line breaks between lines, I also appreciate the comment. I originally agreed with the other poster, but your comment is way better. Especially for having no context :D

mbesto 4y ago

I get your point (yours is written much better), but having comments that feel more like inner monologue is actually a good thing.

billforsternz 4y ago

These are both terrible comments (IMHO) because they tantalise the reader (the coder knew why they did this mysterious thing!) but don't actually really explain why this is necessary or how this mysterious thing actually addresses the messy reality involved. The problem might just be that it's an unrealistic example.

nydev 4y ago
Could be elaborated but this is 1000x better than nothing. The reader can look up what's unusual with enough hints from this comment.
mbesto 4y ago
If you're going to call something terrible, it's a little more productive to offer a suggestion for something better.
- billforsternz 4y ago
  Okay instead of # Call foo_bar only on the 4th loop iteration to handle the weirdness of calculating taxes for California # Call foo_bar only on the 4th iteration because in California widget tax # (1st iteration) doesn't apply at all, foo tax (2nd iter.) only applies # for B2B transactions (this is not one), bar tax (3rd iter.) only applies # for alcohol and this subsystem is not called for alcohol sales. But VAT # (4th iteration) does apply.
  - billforsternz 4y ago
    HN hasn't respected my line breaks.
    - azemetre 4y ago
      I believe you need to have multiple line breaks between lines, I also appreciate the comment. I originally agreed with the other poster, but your comment is way better. Especially for having no context :D