Page Comparison

...

For example, take this Python snippet:

for index, value in enumerate(value_list): 

...

    if index < 100: 

...

        print(f"{value} at position {index}")

Many of us will often, almost out of reflex, add comments like:

# For each element in the value list 

...

for position, value in enumerate(value_list): 

...

    # Check if the index is within the first 100 

...

    if position < 100: 

...

        # Print the value and it's position 

...

        print(f"{value} at position {position}")

We’ve added absolutely nothing of value here though. Even a glancing understanding of the language makes everyone one of these comments a waste of space.

A more useful comment would explain why we do what we do, for example:

for position, value in enumerate(value_list):
    # Only the first 100 values will be entered into the ballot. Discard the rest.
    if position < 100:
        # Print the values to stdout so entries can be verified by-eye
        print(f"{value} at position {position}")

These comments now provide information not available from the code itself. We’ve actually added something useful.

...

For example, our code snippet above would work just fine¹ awfully rewritten as:

for item in [(i, v) for i, v in enumerate(value_list) if i < 100]: 

...

    print("{} at position {}".format(item[1], item[0]))

However since it’s so much less readable it would be tempting to just add a bunch of comments explaining what’s going on. By the time you’ve done that though, you may as well just rewrite it in a clearer format.

¹ I’ve never actually tried this code, so it may not actually work, but it demonstrates a point