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

[Steven D'Aprano]

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'm not entirely sure what you mean by "program file header comments", 
can you give an example?

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.

DVCS is, in some ways, akin to having backups: if you're a home user who 
only uses the computer for playing games, you probably don't care about 
backups ("I lost my Minesweeper top scores!!! What shall I do???"), but 
for everyone else backups of some type or another are essential if you 
are treating your computer seriously.

If you are collaborating with other programmers (or at least *hope* to 
collaborate with others), using a DVCS is all but mandatory, but if 
you're just working on your own, you can avoid using one. You probably 
shouldn't -- even for a single user programming alone, a DVCS makes it 
easier to experiment with your code without fear of irreversibly 
breaking things.

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.

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

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.

Does this help answer your question?


-- 
Steve