Comments are a code smell when they describe things that should be described in code.

Comments are important when they express things that code cannot.

Examples:

// See ticket XYZ-123 for discussion and rationale.

// We are sidestepping a bug in Docker 3.x here.

// TODO: Allow queue size per service version. Currently we're using max size for all.

Great examples. I wonder though if all those could be better expressed using something like decorators in order to enforce some static time checks. For example, instead of a free form comment to do have a structured todo notation that then makes the todo parsible and checkable. Often I see a //todo comment that is still there by accident after the thing is done. Or a todo that has since been abandoned.

Edit: adding a link to the Clean Code bit about comments, which I think is great advice : https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988c...

From the link, about comments:

  Use as explanation of intent.
  Use as clarification of code.
  Use as warning of consequences.

Here's a link to a well-known recent book, half of which is pretty much about why those points are a real and frequent thing, and why code should be much more thoroughly commented than it's recommended by the usual philosophies.

https://www.amazon.com/Philosophy-Software-Design-John-Ouste...

In a JSON config comments can be very useful to "hide" disabled options

["DoStuff", "EvenMore"/, "ops go back :("/]

> If your names and design are well thought out

Sure, but how often does that happen?

It usually happens in good code if the language supports it. But I agree, not enough and comments are great as a stopgap until the thing you need to explain can be explained in the programming language. But sometimes that can’t be and so you do need to resort to comments. It’s like types in doc comments being used as a stopgap until a language added types. I hypothesize (I plan at some point to crunch some data here) the more comments the worse the language, and so you’d see a pattern like Python 3 code having fewer comments on average than Python 2 code.

JSON is data, not code.