Code anntotations (copyright, autor, etc) in your code

[Ben Finney]

Tim Daneliuk <tundra at tundraware.com> 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 <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, 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 <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, 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 = "ben+python at benfinney.id.au"
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