[Tutor] Does the Python way of doing things have a definite preference for the structure and content of program file header comments?

[boB Stepp]

On Thu, Jan 22, 2015 at 5:45 PM, Steven D'Aprano <steve at pearwood.info> wrote:
> On Thu, Jan 22, 2015 at 03:17:58PM -0600, boB Stepp hid the following
> question in the subject line:
>
> "Does the Python way of doing things have a definite preference for the
> structure and content of program file header comments?"
>
> and then wrote:
>
>> And will this vary depending on whether a version control system is
>> being used or not? Or is the use of a version control system
>> considered to be highly recommended (if not mandatory)?
>
> This is a language-agnostic question, it is not specific to Python. It
> may be a question about the community of users for a language, but in
> principle at least it applies to *every language*.

I was wondering if the Python culture had their own particular take on
these types of comments.

> I'm not entirely sure what you mean by "program file header comments",
> can you give an example?

I outlined what I meant in my response to Ben Finney.  Briefly, just
the introductory/explanatory comments made at the very beginning of a
program, describing its purpose, the author, etc.

> As far as version control, I consider it *absolutely essential* for
> anyone who is serious about programming professionalism. Clearly,
> however, I'm not serious, because I only use it about 50% of the time
> *wink*
>
> I consider the use of a DVCS (Distributed Version Control System) such
> as Mercurial or Git to be Best Practice for professional programmers and
> highly recommended for non-professionals. In this case, I'm referring to
> professionalism, not necessarily whether you are paid to program.

I am striving hard to at least make myself aware of what constitutes
"professionalism" in software creation. I fully intend to go in your
stated direction, but finding time to become proficient in such a tool
in the midst of all the other things I am trying to absorb is
difficult. However, my mention of version control was in response to a
web search where many said that including change logs/version history
in a program's header comments is made unnecessary by modern version
control systems and is even harmful in that it might lead to
unmaintained comments. OTH, there seemed to be plenty of others who
advocate that this information should indeed be included in the
program's header comments.

[...]

> Example: some years ago, before starting to use version control, I had a
> working script that I wanted to experiment on. So I made a copy of it,
> and edited the copy. Well, one thing lead to another, and at some point
> I broke the script so badly that I decided to throw it away and start
> again, which I did.
>
> Except that somehow I somehow managed to delete the original, so I was
> left with a non-working, heavily modified (to the point that it was
> almost unrecognisable) copy, and a .pyc (compiled byte-code) version of
> the original, but no source code to the original. Had I been working
> with version control, fixing this would have been easy. But I wasn't.
> Eventually, after many tears and much sweat, I was able to reconstruct
> most of the original from memory, the broken copy, and the byte-code in
> the .pyc file. I had no tests either, so to this day I cannot be sure
> that what I reconstructed does exactly what the original did, or whether
> I have introduced bugs. I surely have, but if I had tests for it, I
> would have quickly discovered where the bugs lie.

Ugh! Unfortunately I have mirrored your example recently, which has
had me wondering whether I should "make" time to implement a DVCS. And
I simply MUST learn how to do test driven development and how to
automate such testing. Dave Angel was absolutely correct (Of course!)
that manual testing is insufficient. The things I am starting to try
to do are just getting too large and complex for manual testing and
manual backups.

> So even for a lone programmer who doesn't share his work with others,
> using version control can be a good thing.

"The Pragmatic Programmer" and some other books I have read in the
past couple of years along with your and other's comments on this list
make it sound better than the invention of sliced bread!

> As far as the Python community goes, that depends. The Python community
> is really many little subcommunities only linked by their use of Python.
> People working on Open Source projects these days pretty much always use
> a version control system. Business programmers may, or may not, it
> depends on whether or not they apply best practices.

"Best practices". "Software craftsmanship". Clarity of code. And
more... As I continue to learn I am appreciating these things more and
more, especially when I must suffer multi-day interruptions to the
project I am working on and have to reconstruct what I had last been
doing/thinking. I find myself almost constantly trying to rename
things to make them more self-explanatory, break things down into more
self-contained, single-purpose constructs, etc. Trying to make my code
more "obvious" as to what it is doing to the casual reader is becoming
much more important to me. So much to learn, and the more I learn the
more I realize I do not know...

> Does this help answer your question?

 Helps considerably on DVCS. Still puzzling over what comments to put
at the very beginning of source code files, so as to enable myself to
more quickly come back up to speed on a project I am taken away from
for a period of time, or to assist someone who comes after me. Style
issues aside, I am suspecting that well-crafted comments are more of
an art than a science and is best learned via painful experience,
which, for me, is coming back to my code after a break and cursing
myself when what I have written is far from being as clear as I
thought it was when I originally wrote it!!!
-- 
boB