This is great feedback. Thanks! Let me provide some additional context. Maybe it will change your mind about some of these examples? But just to be clear, I think all of your takes are reasonable.

> While I agree with the conclusion, I don't agree with all the examples given.

> > Invariant: From this point on the array’s length must be 3N + 1 for some integer N.

> Invariant can be checked by code, and they definitely should if your language allows constraints or asserts (checked at comptime or ran in test and debug mode)

Yeah, it’s hard to tell without the context, but the code’s logic is actually checking (and branching on) this invariant repeatedly. The comment is here to remind the reader of this invariant that was established earlier.

> > We use simple brute force here because instances are guaranteed to be small (see guard above).

> The guard above probably conveys the information already.

The guard only conveys a size limit. It does not convey that the limit is considered small for the brute-force algorithm. Rather than have the reader wonder whether the upper end of the limit is too large for brute force, we answer this question directly at the place it would naturally occur to a reader.

> > Limit each request to one day’s data; otherwise, we won’t get 1-minute resolution.

> This could be a benchmark, though I wouldn't be unhappy to read this as a comment, and I wouldn't care if there was no benchmark.

Without this comment, it would be a mystery why we are adjusting the start of a range. Here’s the actual code. Please let me know whether you think this comment ought to be removed: https://github.com/tmoertel/tempest-personal-weather/blob/ma...

> A couple others could be in a separate technical doc rather than in comment. I'm on the fence about it, a bit more on your side, but there are ways and places to express intent outside of the source code that the "no comments" crowd may argue for.

> As for the python example, it's a great illustration of your point, there are many comments, but it's hard to remove any. Still:

Thanks!

> # Weights must be non-negative integers. and # The distribution must have a positive total weight.

> Can be discarded without losing anything: the parameter validation they comment is already transparent, and even includes natural language in the error message, describing what happens why.

That’s a reasonable conclusion. I prefer to keep those comments, though, as a matter of emphasis. The logic will rely on these mathematical properties, so I didn’t want them to be glossed over as mere input validation.

> Some other comments describe the what rather than the why, but the code it refers to is dense enough that it's warranted.

Agreed :-)

Thanks again for reading my article carefully and for sharing your insightful feedback!