I love header comments, but many people fail to get their usefulness, and I get the "good code does not need comments" mantra recited to me pretty often.

Here is the thing: Header comments are not really about explaining their following code. They are about reducing the lines you need to read to navigate through the code by a factor of 5 to 10. Huge time-saver, and helps a ton newcomers to become productive quickly.

My favorite type of "What" comment is:

  // The following block should have the same
  // result as this (simpler) code:
  //   <code>
  // but for <reason> this version is better

This is great for things like opaque optimizations, things that mimic a library function except for one critical difference, blocks that become really convoluted to deal with special cases, and similar.

> I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful:

I agree. However, "what" comments need a little more skill and judgement to know what to write and what to leave out.

Having a terrible memory helps develop that skill, because you kind of get a sense of what you'll want explained to you again in six months and what's hard to decode.

>> Yes I can that regex, but I can read that comment a lot faster.

Regex is the worst language that everyone needs to know.

I like the joke "if you decide to use regex to solve a problem, you now have two problems"

And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it.

> And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it.

That always gets trotted out, but it's sort of like "don't write code unless you can guarantee the code won't have any bugs, so never write any code."

The trick is write code and comments, but be a little skeptical of both. If you're disciplined (especially with commit messages), it's usually pretty easy to figure out a mistake or omission after the fact.

Next up: comments that dynamically generate from the code itself, like tooltips in a game. /s

"...only from %s domains..."

Like GPT in reverse? I wonder how long it will take before someone tries to use an AI to document code.

I am 99% in agreement with everything you said, so of course I'm going to focus on the 1%! If you have a 4 line stanza that needs a comment to explain what it's doing then I'd suggest that needs breaking out into a function so that your code then becomes `if (is_foobar?(current_user_id)) {do_thing()}`. Just as readable with no comments needed.

There are definitely places where that's hard or impossible and your regex code is a good example of that. I write a fair amount of C at the moment and you can have some pointer arithmetic that's not even that complicated, but a comment on it makes scanning through the function much simpler.

> If you have a 4 line stanza that needs a comment to explain what it's doing then I'd suggest that needs breaking out into a function

I'm mostly in agreement, so I'm going to focus on my disagreement too! ;)

This view is pretty common in the ruby community. So much so that I think they take it too far at times. I sometimes find myself reading a class that could have been a single 24-line method but is instead one method with method calls, each of which calls 0-2 more methods.

This style is good for when I'm trying to quickly understand what that class is supposed to do - I just read the top-level method that looks like:

    thing = getThing()
    munge { |i| thing[i] }
    is_foobar?(thing)

But it's terrible when I need to understand what that function is actually doing - eg to debug it or to find some underlying function call I'm looking for. I have to bounce all over the file to mentally reconstruct a linear sequence of code which could have just been one function with some headers.

Of course, this style is a reaction to impenetrable 500-line functions which are also terrible. I'd definitely prefer many small functions to that! I think it's a matter of judgement and experience to know whether some code is better as small stanzas with comments or small functions.

1. would be better as a function, so you have:

- a nice explanatory name to it

- if the functionality changes then it is more probable that the name would change

- the code is hidden away if you don't care about the why (maybe you are looking for something else)

I like header comments too, but I almost never use them when working on a team.

I feel like there are a bunch of coding habits that work well for solo developers but not devs on a team.

Those are perfect examples of what not to do.