On Mon, 2008-10-20 at 15:27 +0200, Morten Brekkevold wrote:
On Thu, 16 Oct 2008 15:19:12 +0200 Stein Magnus Jodal stein.magnus.jodal@uninett.no wrote:
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*
Alert needed ;-)
You propose to reduce the comment part of the headers, but you do not address the redundancy of this data in Python meta-variables.
Yes, I do. I propose to use the comments, but as long as we use either the variables or the comments, and not both, I'm in.
"Variables: Readable to a human, just like the comments, but also easily extracted programatically. Only the __version__ variable is mentioned in PEP 8. May be preferable to comments, but we do not extract them in any way, so lets just keep to the dead simple comments."
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?
As far as I know, there are no standard here, except PEP 8 stating that you should use __version__ "If you have to have Subversion, CVS, or RCS crud in your source file".
*snip boiled down boilerplate*
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.
May I ask why you believe this is needed? I've read the GPLv2 license a couple of times, but I am in no way tempted to do a third read at the moment.
My problem with the boilerplate is simply its size.
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?
I don't believe that's a fair comparision.
Anyway, how useful is it to be able to blame me for my code in three years time or when debugging a NAV installation? Things like that only serves to discourage oldtimers to hang around in the IRC channel (yes, this is a #ref).
The useful point in time for blaming someone for their code is at or right after the time of commit. That is when the committer still has the piece of code fresh in mind and may actually have the possibility to improve it.
*snip CVS/SVN keyword paragraphs*
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.
IMHO, "A line describing this module." and "Module docstring" says about the same thing. The point here is the placement of the docstring relative to the other elements.
Including PEP-257 in our set of conventions is of course supported.