On Mon, 20 Oct 2008 14:16:42 +0000 Stein Magnus Jodal stein.magnus.jodal@uninett.no wrote:
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".
We've discussed various aspects of the issues in this thread at today's status meeting. While there seem to be no officially documented conventions for metavariable usage in Python files, the __copyright__, __author__ and __license__ variables seem pretty prevalent (just ask Google).
I've come up with this suggestion for Python headers:
---[snip]--- #! /usr/bin/env python # -*- coding: utf-8 -*-
"""Module docstring, using PEP-257 conventions."""
__copyright__ = """ Copyright (C) 2002-2004 Norwegian University of Science and Technology Copyright (C) 2007-2008 UNINETT AS """ __license__ = "GPLv2 http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt" ---[snip]---
An alternate suggestion for the value of __license__ is:
__license__ = """This file is part of Network Administration Visualized (NAV).
NAV is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with NAV. If not, see http://www.gnu.org/licenses/. """
As for "wasting" as little monitor space as possible, as you put it, it's time you upgrade to a real text editor (tm) which can handle more than one monitor page of text :->
I would like to keep the "this file is part of NAV"-part for situations where someone takes a file out of its NAV context.
The snippets above should be easy to adapt into comments in files written in other programming languages.
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.
I think it is needed because not everyone is as intimately aquainted with what a GPL license is or means as you and I are. Also, the disclaimer is a legal precaution, which is why the FSF suggests it in the first place.
We can't expect everyone too look up or recall the entire text of the GPL when they see it mentioned in a file, so we repeat one important sentiment, which has nothing to do with actual redistribution of the software itself: You're on your own.
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.
You seem to be overly preoccupied with blame here. Should I interpret this as though you don't think any of the code you've written is worthy of praise?
I can't see that you've provided any useful or convincing arguments against listing authors in source code. Thomas did, however, present one argument during today's meeting, which actually changed my mind.
Quoting from the Subversion Hacker's guide, http://subversion.tigris.org/hacking.html#other-conventions :
«We have a tradition of not marking files with the names of individual authors (i.e., we don't put lines like "Author: foo" or "@author foo" in a special position at the top of a source file). This is to discourage territoriality — even when a file has only one author, we want to make sure others feel free to make changes. People might be unnecessarily hesitant if someone appears to have staked a personal claim to the file.»
According to Thomas, the Subversion team maintains a file that lists all contributors, much like we do in the about.html file.
We also discussed the old "dilemma": How much do I need to contribute before I can/should add myself to the list of Authors? This dilemma, of course, disappears when Authors are dropped from source files.
I've come to the conclusion that we shouldn't require any sort of Author tagging in our files (though we never did write down such a policy, it remained by convention).
But two questions remain: * Should we start removing Authors-lines willy-nilly right now? * Should we refuse to accept new code which is tagged with Authors?
Including PEP-257 in our set of conventions is of course supported.
It's on my TODO-list for updating the HACKING file (and moving it to the wiki).