Re: coding style (WAS inclusions WAS: Increased company involvement)

[ catching up... ]

James William Pye <pgsql(at)jwp(dot)name> writes:
> I asked on IRC and I'm still curious, does PG have a API styling
> standard/guide? I see formatting and info about error messages, but
> nothing about function/global/typedef naming.

Nothing official, but here's a few random thoughts collected from my
experience:

There's no project-wide standards for names. Given the number of people
who have worked on the code and used different styles, it's probably
hopeless to settle on just one style. I do advise trying to "be like
what you see around you" when working within any existing section of
code.

There is plenty of precedent in the code for both MultiWordName and
multi_word_name, so no one will complain if you use either. There
isn't much of any "Hungarian notation" (that is, using a name like
"iFoo" to denote that the object is of integer type), and personally
I don't care for that so I'd not encourage its introduction.

Macros should usually be named in ALL_CAPS to remind users that they
are macros not functions. This is particularly critical if the macro
doesn't have exact function-call-like semantics (ie, exactly one
evaluation of each argument). If it is a function call equivalent
then it's probably okay to name it like a function.

We're not very consistent about whether symbolic constants (enum values,
paramless constant macros, etc) are in all caps or not.

Avoid exporting stuff that you don't absolutely have to --- eg, make
functions "static" if at all possible. One fairly common exception to
this is that many modules export struct definitions that they maybe
don't have to. I get the impression that this was conventional during
the Berkeley phase of the project, possibly for debugging reasons, but
now I think it's bad style. Export an abstract "struct foo" typedef
instead, if you can.

A somewhat related point: avoid defining APIs in ways that force
widely-used headers to include lesser-used headers. The fewer
#includes in headers the better IMHO, since otherwise you end up
with a completely flat namespace ...

regards, tom lane