file headers

[Robert Collins]

Lets talk about how the top of a source file should look, so we can all
agree that we've agreed :).

Heres what I propose a general file prelude should look like:

The year is obviously the year(s) this file has been worked on it.

The #'s are unbroken so its clear this is one block of comments, not 4
separate ones.

The Authors list there preserves the names of the major authors for this
file. Annotate probably isn't enough: What about when people send in
patches?. What about when we move code between files? We can just record
the global AUTHORS list of course, but IMO a per-file list is a nice
courtesy.

The GPL header is there because its the simplest way to ensure that
people browsing split out source are always able to see the licence that
the code is distributed on.

And finally the doc string is for documentation purposes.

-----------
# Copyright (C) 2006 by Canonical Ltd
#   Authors: Robert Collins <robert.collins at canonical.com>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# 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 this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
USA


"""I document this file """.


---------------


Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060225/b9793185/attachment.pgp