[Tutor] Does the Python way of doing things have a definite preference for the structure and content of program file header comments?
robertvstepp at gmail.com
Fri Jan 23 05:55:46 CET 2015
On Thu, Jan 22, 2015 at 5:25 PM, Ben Finney <ben+python at benfinney.id.au> wrote:
> boB Stepp <robertvstepp at gmail.com> writes:
>> And […]
> Could you write a message body that asks the question? (The Subject
> field isn't part of the message body.)
Does the Python way of doing things have a definite preference for the
structure and content of program file header comments?
> As it is, I'm not sure what in particular you're asking about.
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 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.
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.
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
3) Most of what I found advised a brief statement of the program's purpose.
4) Most mentioned that the code's author should be stated and the
date of creation.
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.
More information about the Tutor