I submitted the patch below my sig way back in August 2002, in ticket 16622. It documented the then-current naming conventions for structures. Is it still accurate and/or a good idea? Should it (or an up-to-date version of it) be committed?
(It's almost certainly been line-wrapped in this message, so get a copy of the patch from the ticket itself if you're gonna try to apply it.)
Parrot_Interp doesn't conform to this, something I tried to solve with ticket 16258, which never got applied. An attempt later to do it failed for reasons I never managed to debug. I may attempt it again once the situation with ICU has settled down.
Thanks, -- Brent "Dax" Royal-Gordon <[EMAIL PROTECTED]> Perl and Parrot hacker
Oceania has always been at war with Eastasia.
Index: docs/pdds/pdd07_codingstd.pod =================================================================== RCS file: /cvs/public/parrot/docs/pdds/pdd07_codingstd.pod,v retrieving revision 1.6 diff -u -r1.6 pdd07_codingstd.pod --- docs/pdds/pdd07_codingstd.pod 17 Jul 2002 02:57:18 -0000 1.6 +++ docs/pdds/pdd07_codingstd.pod 20 Aug 2002 07:09:30 -0000 @@ -371,27 +371,19 @@ =item *
All entities should be prefixed with the name of the subsystem they appear -in, eg C<pmc_foo()>, C<struct io_bar>. They should be further prefixed -with the word 'perl' if they have external visibility or linkage, -namely, non-static functions, plus macros and typedefs etc which appear -in public header files. (Global variables are handled specially; see below.) -For example: - - perlpmc_foo() - struct perlio_bar - typedef struct perlio_bar Perlio_bar - #define PERLPMC_readonly_TEST ... - -In the specific case of the use of global variables and functions -within a subsystem, convenience macros will be defined (in -foo_private.h) that allow use of the shortened name in the case of -functions (ie C<pmc_foo()> instead of \ C<perlpmc_foo()>), and hide the -real representation in the case of global variables. +in, eg C<pmc_foo()>, C<struct io_bar>.
+=item * + +Functions with external visibility should be of the form C<Parrot_foo>, +and should only use typedefs with external visibility (or types defined +in C89). Generally these functions should not be used inside the core, +but this is not a hard and fast rule.
=item *
Variables and structure names should be all lower-case, eg C<pmc_foo>. +See L<"Structures and Typedefs"> for full naming conventions.
=item *
@@ -400,11 +392,12 @@
=item *
-Typedef names should be lower-case except for the first letter, eg -C<Foo_bar>. The exception to this is when the first component is a -short abbreviation, in which case the whole first component may be made -uppercase for readability purposes, eg C<IO_foo> rather than -C<Io_foo>. Structures should generally be typedefed. +Typedef names should be lower-case except for the first letter of each +component, eg C<Foo_Bar>. The exception to this is when the first +component is a short abbreviation, in which case the whole first component +may be made uppercase for readability purposes, eg C<IO_Foo> rather than +C<Io_Foo>. Structures should generally be typedefed. See +L<"Structures and Typedefs"> for full naming conventions.
=item *
@@ -443,8 +436,7 @@
Macros can be defined to cover common flag combinations, in which case they should have C<_SETALL>, C<CLEARALL>, C<_TESTALL> or <_TESTANY> suffixes -as appropriate, to indicate aggregate bits, eg -C<PMC_valid_CLEARALL(foo)> +as appropriate, to indicate aggregate bits, eg C<PMC_valid_CLEARALL(foo)>
=item *
@@ -476,6 +468,29 @@
{ DECL_STACK(sp); x = POPSTACK(sp); ... /* sp may or may not be auto */
{ DECL_STACK; x = POPSTACK; ... /* anybody's guess */+ +=back + +=item Structures and Typedefs + +Structures and typedefs have strict naming conventions designed to make +it obvious at a glance what sort of thing you're dealing with. + +=over 4 + +=item * + +The structure itself must have a name of the form C<struct parrot_foo_t>. + +=item * + +A typedef for internal use must be defined and be of the form C<Foo>. + +=item * + +If the structure has external visibility, a second typedef of the form +C<Parrot_Foo> must be provided; this must be typedefed as a pointer to +the structure.
=back
