boB Stepp <robertvst...@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 _______________________________________________ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor