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@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@geog.uni-hannover.de with
subject 'unsubscribe grass5'
--
Andreas Lange, 65187 Wiesbaden, Germany, Tel. +49 611 807850
Andreas.Lange@Rhein-Main.de - A.C.Lange@GMX.net
----------------------------------------
If you want to unsubscribe from GRASS Development Team mailing list write to:
minordomo@geog.uni-hannover.de with
subject 'unsubscribe grass5'
