Hacker News Reader

Comment by mbesto | Hacker News Reader

The best comments I've seen go something like this:

    # this is going to loop 4x and call foo_bar on the 4th time because when you calculate this number it needs the 4th time to calculate the difference from the sales tax. weird, I know, but the business has special rules about how taxes work in California

View on HN

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

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

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

This is overly expository and could be much shorter. It also shows the programmer had no interested in actually understanding what their code was doing. The comment makes absolutely no sense whatsoever. "It needs the 4th time". What needs it? I absolutely guarantee you you do not need to loop 4 times to "calculate the difference from the sales tax". "Weird, I know" -- I guarantee you it's not weird if you actually understand anything about the calculation you're supposed to be implementing. This comment barely passes as an English sentence, much less someone who knows anything about taxes would ever say. This is such a great example of an absolutely terrible comment belying lazy, thoughtless programming.

I'm not sure I've seen all the "comment everything" advocates in this thread provide a single example of a good comment.

func handleFourTimesForCaliforniaTaxes() {

   for i in 0..<4 {  

      if i == 3 {  

        foo()  

      }  
      else {  

         foo_bar()  

      }  

   }  

}

Reply on news.ycombinator.com