Tim Daneliuk <[email protected]> writes: > mattia wrote: > > Hi all, which are the usual comments that you put at the beginning > > of your code to explain e.g. the author, the usage, the license > > etc?
I use a single-line copyright statement for each distinct holder, and a brief grant of license under some free-software terms. Descriptive stuff about what the module is for goes into the module docstring. > Something along these lines: > > -------------------------------------------------------------------- > #!/usr/bin/env python > # twander - Wander around the file system > # Copyright (c) 2002-2007 TundraWare Inc. All Rights Reserved. > # For Updates See: http://www.tundraware.com/Software/twander Note that a copyright notice: * Is no longer required at all for copyright under the Berne convention, but that leads to the ludicrously common situation that a work is restricted under someone's copyright but the recipient has no way of knowing who that is. Accordingly, I find them to be very helpful as a recipient so continue to put them on my work, and treat with great suspicion those works that lack them. * Needs, to be recognised legally according to the UCC (which, by the Berne convention, is obsolete, but remains the main reference for such notices), the word “Copyright” or one of the abbreviations “Copr.” or “©”. The letter “c” in parentheses has never been a legally-recognised copyright mark, and is useless for that purpose. Either use the copyright mark correctly, or just the word by itself. * No longer needs “All rights reserved”, since that's always the default under copyright law. That phrase is at least entirely useless, and is actively contradictory when one then grants some of those rights under a license — which is almost always the case when distributing the work at all. Best to just drop it. > # Program Information > > PROGNAME = "twander" > RCSID = "$Id: twander.py,v 3.224 2007/01/11 07:08:31 tundra Exp tundra $" > VERSION = RCSID.split()[2] The version of my works is usually a string that is set and changed manually and persists over many revisions, not something derived from the VCS. Here's a typical module header of mine: ===== $ cat gracie/server.py # -*- coding: utf-8 -*- # gracie/server.py # Part of Gracie, an OpenID provider # # Copyright © 2007–2009 Ben Finney <[email protected]> # This is free software; you may copy, modify and/or distribute this work # under the terms of the GNU General Public License, version 2 or later. # No warranty expressed or implied. See the file LICENSE for details. """ Behaviour for OpenID provider server """ ===== Here's the ‘version’ package from Gracie, managed under the Bazaar VCS which exports some useful VCS information into a Python module ‘version_info’. ===== $ cat gracie/version/__init__.py: # -*- coding: utf-8 -*- # gracie/version/__init__.py # Part of Gracie, an OpenID provider # # Copyright © 2008 Ben Finney <[email protected]> # This is free software; you may copy, modify and/or distribute this work # under the terms of the GNU General Public License, version 2 or later. # No warranty expressed or implied. See the file LICENSE for details. """ Version information for the Gracie package """ from version_info import version_info version_info['version_string'] = "0.2.9" version_short = "%(version_string)s" % version_info version_full = "%(version_string)s.r%(revno)s" % version_info version = version_short author_name = "Ben Finney" author_email = "[email protected]" author = "%(author_name)s <%(author_email)s>" % vars() copyright_year_begin = "2007" date = version_info['date'].split(' ', 1)[0] copyright_year = date.split('-')[0] copyright_year_range = copyright_year_begin if copyright_year > copyright_year_begin: copyright_year_range += "–%(copyright_year)s" % vars() copyright = "Copyright © %(copyright_year_range)s %(author)s" % vars() license = "GPL-2+" ===== -- \ “A child of five could understand this. Fetch me a child of | `\ five.” —Groucho Marx | _o__) | Ben Finney -- http://mail.python.org/mailman/listinfo/python-list
