[Xcb] XCB naming conventions

[Carl Worth]

On Wed, 13 Sep 2006 14:19:05 -0400 (EDT), "Jeremy A. Kolb" wrote:
>
> For functions:
> xcb_ followed by the extension and function name all in lowercase, words
> separated by underscores.

Looks perfect.

> For structures/enums/unions etc.:
> Xcb followed by the extension and name with the first letter of
> each word capitalized,

This rule is consistent with GTK+ and much of the GNOME stack, and
there's something to be said for that. For cairo, I deliberately
avoided this StudlyCaps style and instead used underscores and an _t
suffix for cairo type names. Here are some of the reasons I did that:

1) I think LongStudlyCapsNames are very hard to read. From the point
   of view of written English, we use space, not case, to separate
   words, so this kind of naming is unnatural to read. And, while type
   names generally are shorter than function names, they still end up
   having 3 or 4 elements in them, which can make them near impossible
   to read.

2) It's very hard to come up with a good rule for consistent
   capitalization of the type names. Here are some examples from GTK+
   and glib that demonstrate some of the issues:

	GSList GdkRgbCmap GdkXEvent GdkWChar

   How is a poor user to remember that "Cmap" is effectively one word,
   while "SList" and "WChar" are effectively two words, (from the
   point of view of capitalization)?

   I don't think the same problem would appear with an
   underscore-style naming convention, since I cannot imagine anyone
   using _c_map or _w_char instead of the very natural _cmap and
   _wchar [*].

   Another problem with studly caps is acronyms. Take a common acronym
   like PDF. If you shove this into a studly caps name, (please pardon
   the fictional notion of an XCB PDF window for a moment), then you
   have a couple of options. One makes the acronym look funny:

	XcbPdfWindow

   and the other is inconsistent with the
   only-first-letter-capitalized rule:

	XcbPDFWindow

   and also violates the case-separates-words rules. So either choice
   has problems. Worse, there is a choice so users make mistakes, or
   sets of software follow inconsistent approaches.

   In the case of the underscore-style naming it might still look a
   little odd to see an acronym in all lowercase (pdf), but there's a
   huge advantage that there's no ambiguity nor inconsistency so the
   user doesn't waste typing typing/thinking of the wrong names.

3) It's consistent with other library and C99 language elements,
   (pthread_t, int32_t, etc.).

4) Editors such as emacs pick up on the _t suffix and recognize the
   name as a type, (for colorizing, etc.)

Now, with cairo as an experiment, here are some of the complaints,
(some fairly vocal), I've heard about cairo's naming strategy:

1) It's unconventional compared to software stacks such as GNOME, and
   other environments that use StudlyCaps, (Java, etc.).

2) It's hard to distinguish at a glance types from function names
   identifiers, (though see the note above about emacs)

3) It might violate some standard (C99? Posix?) which reserves the _t
   suffix.

I'm still happy with the choice I made in cairo.

I hope that the discussion above might be helpful.

-Carl

[*] Given the choice, I'd still argue that abbreviations don't belong
in names in the first place, but that's a separate issue.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/xcb/attachments/20060913/85a13d07/attachment.pgp