file headers

[Martin Pool]

On 25 Feb 2006, Robert Collins <robertc at robertcollins.net> wrote:
> Lets talk about how the top of a source file should look, so we can all
> agree that we've agreed :).

I agree except

> 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 problem is these things never stay up to date.  It is unclear how
large of a patch ought to cause an addition, people often don't add it
in patches, and as you say when code moves you will not want to dig back
and discover just who updated the code that moved.  In central files you
can end up with a screenfull of names, which seems unhelpful.
Conversely if someone totally replaces the code in a file should they
also remove that line, or leave it as credit for the person who possibly
laid down the previous version?  (I have seen projects which tried to
use the javadoc tags to credit each function, and it becomes a bit
ridiculous.)

When you apply a patch it's a good practice to include the original
author's name in the commit message.

Giving credit is very important and I think the most reasonable way is
in the NEWS file.  It's one thing that should get updated with every
substantial change, and at the time of adding an entry we can add the
relevant names.  It can never go out of date because it's just a
historical record of who did the work at the time.  It has the advantage
of showing the names in the release notes too.  fwiw a similar approach
is followed by the gnu project in changelogs.

In passing I'll remind folks that the docstring must come before the
imports to be seen as a docstring by Python because 'import' statements
count for determining the first statement.

-- 
Martin