[folkrav]

> Comments are a perfectly reasonable way of indicating logical blocks within code.

Comments like these very often end up lying to my face and make me lose precious time. I nowadays tend to semi-ignore them and just read the code anyway. YMMV, I guess.

[communtator]

If you consistently break functions down into tiny “functionettes” the names of the functions can as easily lie to you. You start with `buildURL` but it gets complicated, you break part out into validating the URL, now it should be `buildAndValidateURL` but it’s never updated and the function name “lies”.

I suppose if you prefer to ignore comments, they are more likely to get out of date, which may be why your mileage varies.

[AlotOfReading]

Doesn't even have to be an intentional lie. Sometimes there are just multiple "things" a function could be known as and only one can be chosen for the function name. I recently wrote a function crc() that goes and computes the thing. The comments above it talk about what CRC it is (non-obvious without domain knowledge of CRCs and the different forms polynomials can be written in) and why it was chosen. This commonly done with cryptography as well. AES functions are commonly named rijndael with a comment about the standard or vice versa.

[communtator]

Indeed I agree that it can be difficult or impossible to squeeze all the important information about a function into its signature! And why bother playing golf when that’s literally what the doc string is for?

(Obviously you should endeavor to write good names anyway).

[jonahx]

No more often than the names of the sub-functions themselves becoming inaccurate ime.

At some point the system does depend on its authors doing the right thing.

[folkrav]

The right thing, I can define with code and check for correctness with tests. I guess I mean that if it can be expressed clearly in code, it should.

But I don't completely disagree that they can have their place. They just get used as crutches for unreadable code a lot of time, that's all.