This document is a brief description of the main
coding style conventions in libdwarf.   Many of them
will be obvious from the code, but over time some
accidental diffences crept in.

Code should be indented in multiples of 4 spaces, and
tabs should not be used to indent the source code.
Use the dicheck program to check indenting.

dwarf.h and libdwarf.h must have all arguments commented
out as these are public headers.  Because a  prototype like
int dwarf_example_prototype(Dwarf_Debug foo);
would be made unusable by  a legitimate
preprocessor definition
such as  #define foo +

The struct naming convention is 'struct  Camel_Caps_s' for the
struct and   'Camel_Caps' for any typedef for the struct.
Admittedly having both camel caps
and an underbar is an unusual convention, but it is
the way the coding was begun in the early 1990's and
we should remain consistent now.

All user-referenceable data and functions 
and user_visible types should begin with DW_ or
dwarf_.  Non-static libdwarf global data and functions
should begin with _dwarf (a somewhat questionable
approach, but workable).

Function names should be all lower case with underbars
for readability.

There should never be static data in any function.
Nor should there ever be static data outside of libdwarf
functions.  libdwarf can be called from multiple threads
(but only from one thread per Dwarf_Debug) and multiple
Dwarf_Debug objects can be open at one time.
Instead place such data per-dbg into the Dwarf_Debug structure
in dwarf_opaque.h. Similarly for the producer code.

Function-local variables should be lower-case with
underbars for readability.   It's ok for a small loop
with counters to use single letter names like i or k or m.

structure members should have a struct-specific
2-character prefix to the name (followed by
an underbar). That makes it much
easier to grep for uses of members.

Try to keep lines under 80 characters in length.

Ensure every if() has {} to enclose the actions.

There is a slight preference for if<single space>(
over  if(. Similarly with for (, while (, and switch (.
Not obsessing about these space-issues...

Use libdwarf.h types for all the data objects you define,
though sometimes an 'unsigned' or 'int' or 'size_t' is
ok in restricted circumstances.  Dwarf_Unsigned Dwarf_Signed
are the preferred integer types for general use.

No .c file should ever have an 'extern *' to access some external.
Instead, such external references should be defined in a header file
and every .c with a reference to the external should #include
the relevant header.  Being obsessive about this ensures that when
the definition changes it will match the function declaration.
There are a couple violations of this as of 2012, and those
should be fixed!

------------