Since I'm lying in wait to apply the rules in force within most of the
core to Parrot_Interp, I figured I might as well document them. :^)
--- docs/pdds/pdd07_codingstd.pod 17 Jul 2002 02:57:18 -0000
1.6
+++ docs/pdds/pdd07_codingstd.pod 20 Aug 2002 07:02:15 -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
--Brent Dax <[EMAIL PROTECTED]>
@roles=map {"Parrot $_"} qw(embedding regexen Configure)
"Java golf. That'd be a laugh. 'Look, I done it in 15!' 'Characters?'
'No, classes!'"
--Ferret, in the Monastery
