[Xcb] XCB naming conventions

[Barton C Massey]

I think Carl's naming conventions are great, and heartily
endorse adopting them wholesale.

	Bart

In message <87ejufsgew.wl%cworth at cworth.org> you wrote:
> --===============1218371494==
> Content-Type: multipart/signed;
> 	boundary="pgp-sign-Multipart_Wed_Sep_13_12:41:19_2006-1";
> 	micalg=pgp-sha1; protocol="application/pgp-signature"
> Content-Transfer-Encoding: 7bit
> 
> --pgp-sign-Multipart_Wed_Sep_13_12:41:19_2006-1
> Content-Type: text/plain; charset=US-ASCII
> 
> 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.
> 
> --pgp-sign-Multipart_Wed_Sep_13_12:41:19_2006-1
> Content-Type: application/pgp-signature
> Content-Transfer-Encoding: 7bit
> 
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.3 (GNU/Linux)
> 
> iD8DBQBFCF7n6JDdNq8qSWgRAutsAJ4gHB/70Rzf9okrmgXpBumgFhtGKwCgoJHo
> YenCzGIrYozPA38vkOAlgc4=
> =LFJu
> -----END PGP SIGNATURE-----
> 
> --pgp-sign-Multipart_Wed_Sep_13_12:41:19_2006-1--
> 
> --===============1218371494==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
> --===============1218371494==--