Question regarding commenting code

[Will Ware]

On Tue, 4 Sep 2001, Andrew Gould wrote:
 > When adding comments to scripts, can I insert lines of comments
 > inside a loop block?  For example:
 >
 > for n in a_list:
 > # separate values using spaces as delimiters
 >         a_line = string.split(n)
 > # get the first value
 >         a_value = a_line[0]
 > # print the first value
 >         print a_value

Roman Suzi wrote:

> This is not good.  (reference to style guide)
> ...and this code is hard to maintain. That is why it is bad.

The style guide mentions that a good practice is that comments
should give information beyond what can be inferred from reading
the code. For example,
     i = i + 1  # increment i
is a bad comment because you can figure it out just looking at
the "i = i + 1" part.

That said, a few caveats:

What is "obvious" will vary from person
to person as a function of experience level. I don't know how
long Andrew has been tinkering with Python. After several years
of Python use, I now use string.split frequently, but in my
first couple months I didn't, and I might have found it useful
to include a comment about what it does. Newbies are prone to
frustration easily, and should be given lots of slack.

Style guides are often full of good advice, but it is often mixed
with personal preferences, and a newbie won't be able to tell
them apart, and what weight to assign to each. Guido's personal
style preferences have suffused the Python library and become
the lingua franca, so one sticks to them for social as well as
technical reasons.

If I'm writing a piece of code that I'll never share, I may
want to follow my preferences rather than Guido's. The possible
danger here is that by training myself in preferences that aren't
shared by the community, I'll make it more difficult for myself
to write to community standards when I do want to share code.
Personally I don't have much of a rebellious streak, and Guido's
standards for formatting Python make plenty of sense, so I follow
them even for stuff I'll never share.

If you work as a programmer, you'll move from community to
community periodically, and it will be a handy thing if you can
adopt the standards for the community you're in, rather than
insisting on bringing another set of standards along with you.
Machiavelli pointed out that it's quite costly to bring about a
new order of things, and this should be attempted only when the
current order of things is so screwed up that the waste is
obvious. I once worked with a guy who simply wouldn't indent his
C code at all. It was the elementary-school refrigerator art of
software, truly a horror to behold. It prevented him from
sharing his code, and I think he subconsciously regarded it as
a form of job security. I made a couple suggestions, but he just
kept doing what he was doing.