Hacker News Reader

Comment by q7xvh97o2pDhNrh | Hacker News Reader

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.)

View on HN

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.

Could be elaborated but this is 1000x better than nothing. The reader can look up what's unusual with enough hints from this comment.

If you're going to call something terrible, it's a little more productive to offer a suggestion for something better.

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.

HN hasn't respected my line breaks.

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

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

Reply on news.ycombinator.com