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

Ben Finney ben+python at benfinney.id.au
Fri Jan 23 08:02:23 CET 2015


Ben Finney <ben+python at benfinney.id.au> writes:

> 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.
> […]
> But none of that belongs in the docstring.
>
> […]
> 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’).

An example::

    # -*- coding: utf-8 -*-

    # foo/frob.py
    # Part of FooBar, a garden gnome decoration library.
    #
    # Copyright © 2011–2015 Ben Finney <ben+python at benfinney.id.au>
    #
    # This is free software: you may copy, modify, and/or distribute this work
    # under the terms of the GNU General Public License as published by the
    # Free Software Foundation; version 3 of that license or any later version.
    # No warranty expressed or implied. See the file ‘LICENSE.GPL-3’ for details.

    """ Functionality to frobnicate spangules.

        Each frobnicator conforms to the Weebly-Ruckford standard
        <URL:https://example.com/dingle/dangle/> for input and output
        vraxen.

        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque
        commodo elit eget odio hendrerit sollicitudin ac eget felis.
        Praesent cursus accumsan vehicula. Nullam ac euismod quam,
        tincidunt maximus augue.

        """

    from __future__ import (absolute_import, unicode_literals)

    …

Much of the comment block is there to aid the reader who wants to know
their rights. What is this file? What work is it part of? What rights
are granted in this work? Who holds copyright and when? Which file in
this code base contains the full license text?

These are at the top of each file because frequently a code base will
amalgamate files with different copyright holders, different copyright
years, different license grants, etc. so it's necessary to answer the
questions specifically for each file.


Note that the docstring has a single-line synopsis of the module's
purpose; the remaining paragraphs say only what is likely to be of
interest to the reader of interactive help for the module. The copyright
and other administrivia don't belong there.


Note these absences:

* No full license text. The *grant* of license is there so the reader
  knows a license is granted and what they can do, but the full terms
  can go into a separate named file included in the code base.

* No history of changes. The VCS of the code base is the canonical place
  where that information should be, and a separate “ChangeLog” document
  in the code base can be maintained for a higher-level, feature-based
  change history of interest to recipients.

* Details of the contents of the file. Any objects created in the module
  are available via introspection tools, so duplicating them manually is
  again inviting discrepancies between comments and code.

Hopefully that's some guidance in forming a convention on this matter.

-- 
 \         “Religious faith is the one species of human ignorance that |
  `\     will not admit of even the *possibility* of correction.” —Sam |
_o__)                                 Harris, _The End of Faith_, 2004 |
Ben Finney



More information about the Tutor mailing list