[GRASS-dev] endian & generic library

[Brad Douglas]

On Thu, 2006-05-11 at 17:43 +1200, Hamish wrote:
> Glynn:
> > I'm not sure that a library makes sense; it's probably better for
> > import/export modules to do it themselves. Apart from anything else,
> > it allows the compiler to inline the code; such modules will typically
> > be [de]serialising arrays rather than individual integers.
> 
> They are sufficiently abstruse to encourage subtle mistakes, so having
> them predefined somewhere would be nice. ... What if the endian
> transforms were written as macros (or inline functions) that could be
> #included from a header file when needed? Does that solve both problems?
> The alternative is cut&paste into each module and hope that down the
> road no one changes one version but not the others.

I suppose that is a middle ground.  I don't see any of the macro
pitfalls really applying.  If there are no objections, I'll add them to
include/gis.h.

Something along the lines of:

#define SERIALISZE_INT32_LE(buf, x) do { \
	buf[0] = (x >>  0) & 0xFF;	\
	buf[1] = (x >>  8) & 0xFF;	\
	buf[2] = (x >> 16) & 0xFF;	\
	buf[3] = (x >> 24) & 0xFF;	\
} while(0)

#define DESERIALIZE_INT32_LE(buf) ((buf[0] | (buf[1] << 8) | (buf[2] << 16) | (buf[3] << 24))

...

I'm really against re-writing the same code over and over again, no
matter how trivial (where constraints allow).  Yeah, function calls are
expensive, but human error and trying to upgrade duplication can be far
more expensive.

> Glynn:
> > SUBMITTING isn't supposed to be a tutorial on C programming
> > (even if many contributors badly need one).
> 
> Many of us are researchers who know a little C programming, not the
> other way around. We are lucky to have a few experts around to help
> point out the errs of our ways, but still we need all the help and
> on-the-job training we can get. It may be redundant and beyond the scope
> of the SUBMITTING document to recreate K&R in full, but it wouldn't hurt
> to throw in a small reference section at the end of the document
> pointing to some background info on safe strings, pointers, memory
> allocation, etc., usage; links to other project's SUBMITTING files..

Both you and Glynn have valid points, here.  I would like to see a
separate chapter in the programmer's manual as a HOWTO/tutorial.  We can
use the SUBMITTING* files as a starting point, where applicable.

It looks like some individuals have made some effort in this respect.
Some parts are written in more of a tutorial style (eg. vector
architecture page).

> me:
> > > FWIW, this is what the Linux Kernel's version looks like:
> > >   http://lxr.linux.no/source/Documentation/CodingStyle
> Brad:
> > I believe GRASS should have a similar document that is a bit more
> > expansive and covering design decisions that affect coding style.  I
> > think it would cut down on repeat questions.
> 
> Can you provide some examples of "design decisions"? Just curious.

Decisions made in the past that the majority of us who haven't been here
for the long-haul understand.  Few things have been formalized and there
probably was no reason to do so early on, but GRASS has grown to such a
size that warrants formalization to some extent, IMHO.

Examples?  A weak example is the decision to determine endianess at run
time.  Or the decision to use lib/gis as a repository for functions
common to other libraries (memory allocation, etc.), then some of those
libraries not using lib/gis account of "bloat".

If some of these things sound trivial, it's probably because I take a
very user-centric approach.  I try to gear things to make the user
experience better/easier, perhaps to a fault at times.

Does this help explain my stance a bit better?


-- 
Brad Douglas <rez touchofmadness com>                      KB8UYR
Address: 37.493,-121.924 / WGS84    National Map Corps #TNMC-3785