syntax difference

[Ian Kelly]

On Mon, Jun 18, 2018 at 10:19 AM Rick Johnson
<rantingrickjohnson at gmail.com> wrote:
> And even from the POV of a programmer, comments can be more
> useful if they are ignored than if they are not. Some
> programmers lack the skill required to properly explain the
> workings of an algorithm in natural language, and thus, the
> reader of such a comment will only become confused.
> Likewise, comments are notorious for becoming out-of-sync
> with the code. And at such point, comments are not only
> _confusing_ or _misleading_, no, they have become _lies_.

If this is really your attitude, then I pity anybody who has the
misfortune to work with you. If a comment is wrong, the best course of
action is to fix it. Not to come to the conclusion that all comments
are useless or worse than useless and to therefore swear off reading
all comments forever more.

As most seasoned programmers would say, the most useful comments are
those that explain why, not what or how. What the code does or how it
does it can generally be understood just by reading the code. *Why*
the code does what it does often cannot. Here's an example of a bad
comment:

def num_threads():
    # Use 10 threads.
    return 20

We easily see the value is 20, but *should* it be 10 or 20? We don't
know. Now here's an example of a useful comment:

def num_threads():
    # Use 10 threads because the system randomly
    # locks up at 15 or more. (bug: 12345)
    return 20

This one makes it clear that whoever increased the value from 10 to 20
wasn't paying attention. The change should likely be reverted.

I would also note that none of this applies to type hinting in any
case. Type hints don't require the programmer to be able to explain
anything in natural language, nor are they prone to becoming
out-of-sync. Because if they do, then then the type analyzer will
complain the very next time you run it. So if you're trying to make
the case for type hints being treated like comments, this isn't it.