[GRASS5] Jan's copyright notice ++

[Justin Hickey]

Hello all

I'll try to answer everyone's concerns in this single post. 

First of all, it appears people got the wrong impression about the
purpose section, mainly due to my poor choice of an example. My intended
audience for the purpose section was for programmers, not users. More
details on this are below.

Andreas

It might just be me, but I don't think I understand your proposal. Where
is the information stored, in XML files? And how does it get inserted
into the source file? But I agree that if there is a possibility of
having effort duplicated, then a system should be developed to avoid
this. My main concern is that this information appears in the source
file, for easy access by other programmers trying to make changes.

Frank Warmerdam wrote:
> I would agree that we shouldn't spend much time putting in purposes
> for GRASS commands, since that is already addressed in the user help
> (in the .html file).

The reason I want the purpose in the file header is to give an
indication of what the code in the file does. This information is mainly
for the programmer, not the user. Although it can contain information
pertinent to users, it should also contain information that a programmer
needs to help him/her determine what the code does in order to make
changes to the code. One of my biggest frustrations with Grass
programming is trying to figure out what code does. I realize that most
programmers do not comment code to the extent that I do (most of my
source files have more lines of comments than lines of code :), so I was
trying to come up with a way to minimize this frustration in the future
that would not be too inconvenient to other programmers.

Reading my example again, I see that the PURPOSE statement is not a good
reflection of what I intended. That's because it was taken from a file I
created which contains much more information throughout the file (I even
have a header for each function). Sorry, bad choice on my part :(.
Anyway, I was thinking the purpose section would be very useful in
modules like v.digit which contains many source files. Obviously, the
purpose sections of most of those files would not contain information
that would be included in a manual page (html file), but could assist
programmers that want to add a new feature or something. Possibly making
it easier to determine which files need to be changed.

> There is no way of instructing CVS to restrict the number of versions
> inserted that i know of.  Normally I just hand trim the history when I
> see it getting very long.  I would also suggest omitting the $Log$
> from files like gisdefs.h that are likely to be updated very
> frequently with additions of prototypes and so forth.

The log idea is a good one, but my only problem is your suggestion to
not include it in some files. The problem is how do we determine which
files should not include it. There should be a systematic way to
determine this but I can't see how it could be done systematically.

I would suggest that the log tag be included in every file for
consistency sake and then if a programmer finds the log entries section
too long, they are free to delete some of the earlier ones. But we
should also limit the number of deletions. For example, we might say
that if you delete log entries you must leave at least the last 10
entries or some other number we can agree on. What do you think?
 
> Shall we say the proposed header for library source files will be as
> shown below?  

Yes, your example is fine. I agree that the sections you dropped are
redundant with CVS.

> For grass commands the purpose might be as simple as
> "Mainline for r.in.gdal" with the user documentation existing
> elsewhere.  If a command is split into several files, the purpose
> should try to address what part of the overall work is done in that
> source file.

Just to add to what I said above, I would also suggest that we should
encourage programmers to fill in the details of their work in this
section, especially if they do not like putting many comments throughout
their code. I am not suggesting that programmers include all the details
of the code, only a general overview so that other programmers can get a
feel for what the code is trying to do before they tackle the code.
Perhaps an Executive Summary of a report would be a good analogy. Even I
have not been creating very relevent purpose sections, as indicated by
my example, but after reading the comments in this thread, I think such
a code overview would be useful for helping programmers determine what
the code does. 

> > What does MODULE mean?  Is this effectively the directory the files
> > is in? Would it be "raster" for src/raster/r.in.gdal?   Please
> > explain more fully.
> For the next major release we want to get GRASS modularized. A package
> "GRASS-core", "GRASS-hydrology" or something like that.
> The idea of "MODULE" (I guess) might be to describe where is file is
> located. On the other hand it might be redundant.

This section I mainly use for hard copies. When I have code in different
libraries and modules, I find it easy to sort and find the different
hard copies with this information at the top. BTW, for
src/raster/r.in.gdal it would have been r.in.gdal. However, Markus has a
good point. In the new structure, it may be useful to note which part of
the new system the file belongs to (GRASS-core, GRASS-hydrology, etc).
It is fine with me if you want to drop it though.

I think I covered everything but if I missed something then please feel
free to point it out.

-- 
Sincerely,

Jazzman (a.k.a. Justin Hickey)  e-mail: jhickey at hpcc.nectec.or.th
High Performance Computing Center
National Electronics and Computer Technology Center (NECTEC)
Bangkok, Thailand
==================================================================
People who think they know everything are very irritating to those
of us who do.  ---Anonymous

Jazz and Trek Rule!!!
==================================================================

---------------------------------------- 
If you want to unsubscribe from GRASS Development Team mailing list write to:
minordomo at geog.uni-hannover.de with
subject 'unsubscribe grass5'