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.
|_|_) | |
| | | h...@hjp.at | -- Charles Stross, "Creative writing
__/ | http://www.hjp.at/ | challenge!"
signature.asc
Description: PGP signature
-- https://mail.python.org/mailman/listinfo/python-list
