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

[Ben Finney]

boB Stepp <robertvstepp at gmail.com> writes:

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

To my knowledge, the term “program file header comments” for Python
would best describe a module docstring; not a comment, but documentation
<URL:https://docs.python.org/3/glossary.html#term-docstring>.

It seems from what follows that this is what you're asking about; I'll
assume so.

> I am asking about what is considered "good practice" in what to
> include in the introductory comments to a program, just after the
> shebang line.

I would consider it good practice to have a copyright statement and a
grant of license at the top; a handful of lines should suffice.

That way it's very easy for anyone diving into the code (as programmers
tend to do when looking around a code base) to see what rights they have
been granted to the code, without needing to engage in a lot of effort.

But none of that belongs in the docstring.

> I had done a web search, but had found a surprising variety of
> thoughts on this. Since the Python community culture seems to have
> strong opinions on making code and its explanation (where needed) as
> simple, direct and clear as possible, I was wondering if there existed
> similar opinions about this area of program comments.

There is PEP 257 <URL:https://www.python.org/dev/peps/pep-0257/> which
defines the format a docstring should conform to.

As for the content, I would advise the module docstring should contain a
concise description of the module's purpose, and anything unusual about
its API. Consider that the primary reader of that content will be a
programmer using the Python interactive help (e.g. ‘pydoc’).

> Some opinions (paraphrased from memory) I've found on this:
>     1) College courses usually have some blurb about including the
> course name, assignment name/number and an explanation of what the
> program proposes to do.

That might be useful depending on the institution, I suppose.

>     2) Some advise including information such as the file name, other
> files called by the program, global variables used, etc. Others advise
> that this type of information is superfluous and should not be
> included.

Right, a lot of that should either be in unit tests, or gathered
automatically from introspection tools. Writing it in
manually-maintained comments invites the comments and code getting out
of sync without anyone realising the error.

>     3) Most of what I found advised a brief statement of the program's purpose.

That definitely belongs in the module docstring, IMO. Anyone reading
‘pydoc’ or other interactive help is likely to need a reminder of this
module's intended purpose.

>     4) Most mentioned that the code's author should be stated and the
> date of creation.

Not in the docstring, but I certainly want to see a concise copyright
statement and grant of license (under free-software terms, please).

>     5) Some advised to keep the change log/version info here. Others
> very strongly said no way, that is the function of version control
> systems, which make such records redundant and just something that
> might not be kept up to date.

Certainly, the VCS is the correct repository of that information.
Duplicating it leads to disagreements between the VCS and the code
comments as to the history of the file.

>     6) Etc.

Hope that helps.

-- 
 \       “For fast acting relief, try slowing down.” —Jane Wagner, via |
  `\                                                       Lily Tomlin |
_o__)                                                                  |
Ben Finney