Friday Finking: Contorted loops

[Peter J. Holzer]

On 2021-09-12 17:11:58 -0400, Avi Gross via Python-list wrote:
> Yes, large units of code, and even smaller ones, may be a chore to figure
> out. Arguably harder when you use indentation and the next/last parts are
> not even on the same screen as the rest. Sometimes you want to use a
> split-screen in some editor to line up the two parts or some other
> technique.
> 
> But my suggestion is to COMMENT things well and I mean too much!
> 
> do {
>    <CODE>
>   } while <COND>
> 
> Why not add a comment at the top like:
> 
> # The following loop has a WHILE clause controlling it at the end.
> 
> do { # until the while clause below
>    <CODE>
>   } while <COND> # End of the do loop.

Because those comments don't tell me anything that I as a C programmer
don't already know. Even though do/while loops are relatively rare, I've
seen hundreds of them. Seeing "do {" and recognizing it as the top of a
do/while loop takes absolutely no conscious thought - reading a comment
does.

> My code tends to have brief comments especially when I have nested
> constructs such as multiple nested loops or in sequence, or if statements
> inside others. The comment often looks like
> 
> ... # END of inner if 
> 
> ... # END of outer if

Those are a bit better, but they still don't help much. What is the
"inner if", what is the "outer if"? Chances are that I have to find the
corresponding if to find out - I can do that without a comment, too.

There are end-of-construct comments which I do find useful (at least
occasionally) but those are semantic.

Imagine a somewhat longish function which read several files which are
comprised of records which are comprised of field.

for file in files:

    some setup for each file here

    for record in file:

        some setup for each record here

        for field in record:

            process field

        do some postprocessing for the record

    do some postprocessing for the file

If each of these blocks is longer than a few lines you might lose track
where you are, so some comments might help:

for file in files:

    some setup for each file here

    for record in file:

        some setup for each record here

        for field in record:

            process field

        # end of field loop

        do some postprocessing for the record

    # end of record loop

    do some postprocessing for the file

# end of file loop


Note that the comments say which part of the input the loop is
processing, not just that it is the end of a loop or "the outer loop",
"the intermediate loop" and "the inner loop" or some other purely
syntactic information.

(In most cases I would just break up such a function into smaller
functions instead of adding comments, though)

        hp

-- 
   _  | Peter J. Holzer    | Story must make more sense than reality.
|_|_) |                    |
| |   | hjp at hjp.at         |    -- Charles Stross, "Creative writing
__/   | http://www.hjp.at/ |       challenge!"
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://mail.python.org/pipermail/python-list/attachments/20210913/50268e61/attachment.sig>