On Thu, 16 Oct 2008 15:19:12 +0200 Stein Magnus Jodal stein.magnus.jodal@uninett.no wrote:
Hi,
I've written up a proposal on what source file headers should contain at [1]. Comments, changes, questions welcome from everyone. Approval of the proposal welcome from Vidar and/or Morten.
Good initiative, I have some comments. *Verbosity alert*
You propose to reduce the comment part of the headers, but you do not address the redundancy of this data in Python meta-variables.
I like the idea of having this data machine-readable, but I'm not certain whether the usage of these meta-variables in Python are standardized somehow. I know that at least the __author__ variable is parsed and displayed in a section of its own by pydoc, for instance. Anyone know of any attempt to standardize or make a common convention out of these variables?
The boilerplate header text you propose to remove comes directly from the suggestions in the GPL howto [1]. The boilerplate text boils (!) down to the following parts:
* Copyright notices. * "This file is part of software X." * "software X (and thus this file) can be redistributed under the terms of the GPL" * Disclaimer of warranty * Where to find the text of the license
Releasing our work under the GPL does, AFAIK, in no way require us to use this boilerplate text as is or at all. I was initially leaning towards supporting your idea of reducing the boilerplate, but having read the boilerplate and the howto over again, I'm not so sure.
I now think we should change the boilerplate somewhat to explicitly state that the software can be redistributed under the terms of the GPL _v2_, which was the original intention, but that we should still include a boilerplate in all files with any meaningful/significant piece of code. I.e. a mostly empty __init__.py file doesn't need any boilerplate, but once you start tossing some real code into it, the boilerplate should be added.
As for dropping author information from source code, I'm against it. Files more often than not appear in non-VCS contexts, and this piece of (dis)credit to the authors should be part of the file contents. You don't remove your name from your master's thesis just because that piece of information is available in the VCS you stored your thesis in, do you?
With regards to SVN keywords, most of these actually come from the good (kidding!) old CVS days. These were brought unchanged into SVN, and keyword substitution was enabled in SVN for most of these files. This functionality is also available in Mercurial (although as a plugin, methinks), but so far we haven't enabled it.
I've always thought of the $Id$ keyword as a useful tool for debugging problems where people have been mixing and matching several branches or trunk revisions onto their development servers. In practice, however, I've barely used it for anything, so I wouldn't miss it if we removed it. The other keywords in use are just variants of the Id keyword, which are there to fulfill the same purpose. I don't think I've added the keyword to any files I've created in a long time.
As a side issue, the docstring from your proposed Python header example says "A line describing this module.". We're not attempting to define docstring policy for modules here, so it should suffice to say "Module docstring". We tell people to use PEP-8 [1] as our Python code style guide. This PEP also references PEP-257 [2], which documents docstring conventions; I also think we should adopt this PEP along with PEP-8.
[1] http://www.gnu.org/licenses/gpl-howto.html [2] http://www.python.org/dev/peps/pep-0008/ [3] http://www.python.org/dev/peps/pep-0257/