Re: [FR-devel] Standard source code header.

[Laurent Julliard]

Curt Hibbs wrote:

> Laurent Julliard wrote:
>
> > I'm a bit reluctant to include any kind of link to a location that is
> > subject to change. if one day we migrate our CVS tree elsewhere or even
> > Savannah changes the way it references change logs of a given file then
> > we must go through all the headers and modify them. Tedious...
> >
> > I had the same doubt with referencing people's email in the header
> > because email addresses tend to change as well so may be email could be
> > optional.
>
> I think that you raise some reasonable issue. I have a couple thoughts and
> questions.
>
> While it is possible for anything to change (web addresses, email
> addresses), in our inter-networked world it also seems reasonable to include
> links to relevant information. But we want to make sure that things we link
> to are reasonably stable.
>
> So my question is, what do we consider to be stable enough that we can link
> to it? Can we link to our Savannah project pages? What about our rubyide.org
> wiki pages? (BTW, Rich and I tried to purchase freeride.org from its owner,
> but he wouldn't sell.)
>
> I like the idea of using the CVS log for the history. If we decide its a bad
> idea to include an actual link we could include a textual reference ("See
> the CVS log for file history."), leaving it up to the reader to know where
> the FreeRIDE CVS repository is located.
>
> Or would including a link be OK, because if the location did change, we
> could easily do a global change on the source code to fix it. On the other
> hand, if we started to have many different types of references like this, I
> could see how it could get unmanageable.
>
> I've got mixed feelings on this and could go either way, although I really
> like the idea of taking advantage of modern hyper linking.
>
> Comments?


I'm really reluctant to any kind of hyperlink in the header. THis kind 
of information should typically be included in the top README file where 
you give:

- a brief overview of the project
- a pointer to the Web site (Wiki page)
- how to get the source code (CVS on Savannah)
- how to submit bug or support request (Savannah again)
- how to suscribe to mailing lists

Everybody knows what to expect from a README file and I don't think 
necessary to clutter the introductory header of each source file with 
redundant information.

The goal of this header is really sort of legal: say who the author is 
and to which "entity" this file belong to.

On a second thought the header should not say "Written by"  but should 
have a Copyright Statement. This is because we do not belong to an 
entity to which we can assign the Copyright so we must keep it the 
individual level.

So the header should be something like this:

# Purpose: what this file is all about (2-3 lines maximum)
# ....
# $Id$   (<- CVS standard header for version number and date)
#
# Copyright (C) Year, Author's name  <email>. All rights reserved.
# Modified by: Author's name <email>
#
# This file is part of the FreeRIDE project
#
# This application is free software; you can redistribute it and/or
# modify it under the terms of the Ruby license defined in the
# COPYING file.
#


Laurent