Re: [boost] Two minor (?) legal-related questions

Subject: Re: [boost] Two minor (?) legal-related questions
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2009-01-31 06:42:23

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
On
> Behalf Of James Fowler
> Sent: 28 January 2009 22:36
> To: boost_at_[hidden]
> Subject: Re: [boost] Two minor (?) legal-related questions
> 
> IANAL, but I have worked with quite a bit with both doxygen and
> 
> licensing issues. As I understand it anything related to protecting IP
> is best applied as consistently as possible.  Aesthetically, I'd prefer
> to have the doxygen block first, but that might add some (admittedly
> small) amount of risk.   If it was just a copyright statement, it would
> probably be too trivial to bother, but referring to an external license
> agreement is a more complex issue.   I'm not really sure it matters, but
> I'm 99.88% certain that if it does matter, it's best to always have the
> copyright / license block at the very beginning.
> 
> My $0.02 : doxygen's more flexible than lawyers, keep the
> copyright/license block first.  FWIW, that's how I format my own code,
> even though I think it's uglier.  .
>

I'm struggling to believe that even lawyers are that picky, but could we run
this by our 'tame and friendly' legal adviser?

Our current guideline at http://www.boost.org/development/requirements.html
says

Begin all source files (including programs, headers, scripts, etc.) with:

    * A comment line describing the contents of the file.
    * Comments describing copyright and licensing: again, the preferred form
is indicated in the license information page
    * Note that developers should not provide a copy of LICENSE_1_0.txt with
their libraries: Boost distributions already include a copy in the Boost
root directory.
    * A comment line referencing your library on the Boost web site. For
example:

The comment line I presume includes a Doxygenated comment

/*! \file my_stuff.hpp
  \brief This does stuff.
 \details Blah, blah...
 \author Paul A. Bristow
*/
...

http://www.boost.org/development/header.html

Unless multiple inclusion is intended, wrap the header in #ifndef guards.
Use a naming convention that minimizes the chance of clashes with macro
names from other's code. The sample header uses the Boost convention of all
uppercase letters, with the header name prefixed by the namespace name, and
suffixed with HPP, separated by underscores.

The example given is

//  Boost general library furball.hpp header file
---------------------------//

  < Copyright and license notice, as indicated in the license page >

//  See http://www.boost.org/ for latest version.

#ifndef BOOST_FURBALL_HPP
#define BOOST_FURBALL_HPP

...

It was suggested that the include guard should come first.  Does this really
have any advantage?

Personally I think the current recommendations are right.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal, UK   LA8 8AB
[phone], mobile [phone]
pbristow_at_[hidden]