[Openeeg-list] Considerations

[Dave F. <df...@po...>]

[crossposted to both Yahoo and Sourceforge list, please respond on Sourceforge
openeeg-list]

Some project related considerations:

Licensing
----------------------------------------------------------------------------

Notice that I have been using Larry Wall's (the author of Perl) "Artistic"
license for my stuff.  This may not be the best choice now that I think about
it (a scripting language is different from an SDK), but I chose it because it
represents a nice balance between the more strict GPL style license and more
lax BSD style.  I personally lean more toward BSD style, though.  My reasoning
is that a support library can be protected as an open-source project, but
spin-off applications using that library have the prerogative of being either
open or closed.  Even if someone chooses to create a closed app, it would
behoove them to be involved in contributing to the open-source supporting
library.  While I know that wars have been fought over this issue (and I have
*no* desire to have that happen!), I see that the licensing strategy posted on
Sourceforge is GPL.  If there is no interest in any of the more balanced
licensing strategies, can we at least change this to LGPL for the SDK?

A more comprensive discussion for licensing strategies can be found here:

http://www.stromian.com/Public_Licenses.html

Copyright
----------------------------------------------------------------------------

I have removed my Copyright line from all the source code files.  Does anyone
have a suggestion for what kind of Copyright notice should be included in the
header of every source code module?  Can the group as an entity carry the
copyright (as in "Copyright (c) 2002, OpenEEG Source Code Project", or does
this need to be a legally recognized entity (such as a person or corporation)?


Source Code Guidelines
----------------------------------------------------------------------------

I recall some discussion on this a while back.  I feel that we need some kind
of framework (and there are *many* examples of guidelines posted for different
projects on the web).  However, I personally do not want to take this to the
extreme where every jot and tiddle is defined, right down to how many spaces
exists between the parenthesis on if-statements or whether you part your hair
on the left or on the right (or not at all, for that matter).

Perhaps the most picky thing we can agree upon are the use of braces.  There
are three popular methods right now, from the original K&R way:

if ( ... ) {
    [do something]
}

to the 80's way

if ( ... )
    {
    [do something]
    }

to the 90's way

if ( ... )
{
    [do something]
}

Personally, I have used all three and am currently using the 90's way.  Who
knows, perhaps we'll come up with another way?

I also see a lot of merit in *documenting* the code internally.  Not only will
this help other programmers to know what was going on in your head when you
wrote something like:

[thread creation code... then]

if ( !thread )
{
    thread = new DummyThread;
    Thread::_self.setKey(thread);
}

return( thread );

It will also help *you* to remember what in the world you were doing months
later when you come back to certain sections of code.  The above, btw, is a
real example that led me to abandon Common C++ (as well as Andreas' suggestion
and coaxing :).  For example, why is a new instance of a thread being created
that has nothing to do with the currently running thread or thread that you are
trying to create?  It led to erroneous results in my own threaded application,
and I have no idea what the rationale was for allocating a "fake" thread
on-the-fly rather than generating an exception.  Documentation would have
helped immensely here after I tracked the error down to this little section of
code deep in their own library.

Doxygen notation

I *love* Doxygen!  It is a great way to create class documentation.  For an
example of an old version of one of my previous alpha-alpha libraries, go here:

http://www.psychosensory.com/linuxeeg/sourcedocs/index.html

Some guidelines to remember are:

Use @author for each class.  This will help us know where to direct questions.
Use @param and @return for each method.
Use @see when appropriate.

Use:

/**
 * Class documentation here...
 */

to document classes and methods (and I think variables, but I'll have to
double-check that).  The "/**" notation signals doxygen that this is a
documentated item.

See http://www.stack.nl/~dimitri/doxygen/docblocks.html#docblocks for more
information.

There are two primarily styles -- JavaDoc and Qt.  I think JavaDoc makes more
sense and just plain looks prettier. :)


"FIXME:" notation

You will notice that I use the notation "FIXME:" in the source code when I come
to a place that either needs work, change, or is just a short-term patch for a
problem that needs more attention.  This is a helpful way to get a change in
place that works, but is not fully complete.  It is a way of acknowledging that
sometimes we do things for an immediate fix, or because an idea is not fully
implementated, or that we lack all the information we need to accomplish a
task, and will need to resolve it more fully later.  Noting when we are doing
this in the code makes for better robust code later as those kinds of changes
will not become a part of a working, final release.

There are other issues that I'm sure we'll want to consider, but that's all
come to mind right now.  Well, not true, but that's all I want to talk about.
;-)

Tim, is this the kind of information that can be folded into the FAQ, perhaps
something under the Software section?  I don't think I've mentioned it before,
but a FAQ was an excellent idea and really helpful for new people coming on
board.  Combined with Michal's notes, I can see this being a valuable resource.
 Perhaps it should be checked into CVS complete with revision history so that
other's can add to it?  Do you have aspirations of being the local
Documentation/Tech Writer?  Pretty please? :)

Dave.