[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 Fri, Jan 23, 2015 at 12:10:38AM -0600, boB Stepp wrote:
> 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.

A good place to learn about Python culture is to look at the standard 
library.

Assuming you are using Python 2.7, you can look at the .py files in some 
place like /usr/lib/python2.7/ or /usr/local/lib/python2.7/ on Linux. If 
you have trouble locating the standard library, run this:

import warnings
print warnings.__file__


and it will print the location of the warnings module from the standard 
library. (Standard disclaimer applies: if you have created a file called 
"warnings.py", it will shadow the standard module.)

Have a look at the sort of thing that the standard library does. 
(Remember not to edit the files, lest you break them.)

If you don't like the idea of poking around in the standard library with 
an editor, you can also see the files on the web. Go to the Python docs, 
choose a module, and many of them will include a read-only link to the 
source code, e.g.:

https://docs.python.org/2/library/pprint.html

has a link to:

https://hg.python.org/cpython/file/2.7/Lib/pprint.py


You might also like to see the sort of thing I put in my modules:

http://code.google.com/p/pyprimes/source/browse/

[...]
> 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. 

I know. So many things to learn, so many distractions, so little time...

> 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.

My take on this is:

- your version control system will track the minutiae of your changes;

- you should have a separate CHANGELOG file as part of your project, 
  where you put the "important" changes that will be of interest to 
  your users;

- keep the change log out of the source code.

So, from my "pyprimes" project linked to above, you can see my change 
log file here:

http://code.google.com/p/pyprimes/source/browse/CHANGES.txt

That's the things I think are important enough to mention. Because 
the change log itself is under version control, you can look back at 
each revision and see how the change log itself changes. 

And here are all the individual changes, as recorded by the version 
control system:

http://code.google.com/p/pyprimes/source/list


> Ugh! Unfortunately I have mirrored your example recently, which has
> had me wondering whether I should "make" time to implement a DVCS.

By "implement", I trust you don't mean "write your own" :-)

There's a good tutorial for Mercurial, or hg, writen by Joel Spolsky:

http://hginit.com/


[...]
> "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...

That is excellent! If you are busy or suffer a lot of distractions, 
*you* are your own Number 1 casual reader.

Actually, even if you are not distracted, comments and good naming 
conventions are essential. A few days ago, one of the programmers I work 
with was bitterly complaining about some code. Let's call him Trevor 
(not his real name). After a while, he went quiet, then called out 
"Stupid yesterday Trevor!" -- it was his own code, written just one day 
ago, and he couldn't work out what it did.




-- 
Steve