[GRASS5] Jan's copyright notice ++

[Andreas Lange]

Hi Justin, hi all,

thank you very much for your comments. I am sorry that i was not clear
about my proposal, i fear that this was only understandable with
knowledge from some personal communication with Markus and Jan-Oliver.
As it will not be possible to add my idea in GRASS5.0stable i will
postpone this. In outline: I want to add a function G_define_module() to
the parser that allows to define title, author, version and a short
description of the module from within the module. This would allow to
add author(s), title, version and the description to the xml output with
--interface-description. This information is then usable for the GUI
(window title, description, help system, searching for keywords), with
G_usage() output and could be processed for automatic generation of the
html-index-pages. This all would be a part of "modularization" of GRASS
and help keeping all information in one place (e. g. from source header,
tcltkgrass-modules-files, html-index-pages, etc). But i don't know if it
is realistically possible to include this in all modules. 

You are right that for big parts of the GRASS code there is not much
documentation of how and why something is done the way it is. I am
frustrated, too, by the lack of comments and sometimes obscure
programming style (this was ok as long as GRASS was maintained within
CERL). There are large parts of code for which there is not even
documentation in the programmers handbook (some R_* functions, whole
XDRIVER/fifos stuff). 

I agree with the header structure as it is now. I have only one
additional question: What should be written for AUTHOR(S) for code where
the author is not known? We should define something here. 

Another concern are the log messages. If i do a back envelope
calculation here: we have over 300 modules, if every module consists of
average 3 files and we add 10 lines to each, we get additional 9000
lines of code to store in CVS. As we add the log messages to the
libraries and add the header with further 10 lines, we should calculate
to add about 20.000 or 30.000 lines to the code in the long run. Will
this cause any problems? I simply don't know. The log messages could be
generated from CVS, so it would be less convinient to the programmer if
we do not store them with the source files.  

cu,
Andreas

Justin Hickey wrote:
> 
> 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'

-- 
Andreas Lange, 65187 Wiesbaden, Germany, Tel. +49 611 807850
Andreas.Lange at Rhein-Main.de - A.C.Lange at GMX.net



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