Author: paultcochrane
Date: Tue Sep 11 06:27:26 2007
New Revision: 21183
Modified:
trunk/docs/pdds/pdd07_codingstd.pod
Log:
[pdd] Minor textual and formatting cleanups.
Modified: trunk/docs/pdds/pdd07_codingstd.pod
==============================================================================
--- trunk/docs/pdds/pdd07_codingstd.pod (original)
+++ trunk/docs/pdds/pdd07_codingstd.pod Tue Sep 11 06:27:26 2007
@@ -388,7 +388,7 @@
Parrot is a large program maintained by many people. Therefore:
Don't use a C<char *> when a Parrot STRING would suffice. Don't use a C array
-when a Parrot array PMC would suffice. If do use a C<char *> or C array,
+when a Parrot array PMC would suffice. If you do use a C<char *> or C array,
check and recheck your code for even the slightest possibility of buffer
overflow or memory leak.
@@ -489,10 +489,12 @@
svn propedit svn:ignore <PATH>
In order to keep the two different checks synchronized,
-the MANIFEST and MANIFEST.SKIP file should be regenerated with:
+the MANIFEST and MANIFEST.SKIP files should be regenerated with:
perl tools/dev/mk_manifest_and_skip.pl
+and the files then committed to the Parrot svn repository.
+
=head3 svn:mime-type
The C<svn:mime-type> property must be set to C<text/plain> for all test
@@ -506,6 +508,9 @@
[auto-props]
*.t = svn:mime-type=text/plain
+The F<t/distro/file_metadata.t> test checks that the files needing
+this property have it set.
+
=head3 svn:keywords
The C<svn:keywords> property should be set to:
@@ -557,7 +562,7 @@
=item Subsystems and APIs
The Parrot core will be split into a number of subsystems, each with an
-associated API. For the purposes of naming files, data structures, etc, each
+associated API. For the purposes of naming files, data structures, etc., each
subsystem will be assigned a short nickname, e.g. I<pmc>, I<gc>, I<io>. All
code
within the core will belong to a subsystem; miscellaneous code with no obvious
home will be placed in the special subsystem called I<misc>.
@@ -582,13 +587,13 @@
this is not essential.
Each subsystem I<foo> should supply the following files. This arrangement is
-based on the assumption that each subsystem will - as far as is practical -
+based on the assumption that each subsystem will -- as far as is practical --
present an opaque interface to all other subsystems within the core, as well as
to extensions and embeddings.
=over 4
-=item foo.h
+=item C<foo.h>
This contains all the declarations needed for external users of that API (and
nothing more), i.e. it defines the API. It is permissible for the API to
include
@@ -596,7 +601,7 @@
with its use in extensions and embeddings. In this case, the extra stuff within
the file is enabled by testing for the macro C<PERL_IN_CORE>.
-=item foo_private.h
+=item C<foo_private.h>
This contains declarations used internally by that subsystem, and which must
only be included within source files associated the subsystem. This file
@@ -605,20 +610,20 @@
used to define shorter working names for functions without the perl prefix (see
below).
-=item foo_globals.h
+=item C<foo_globals.h>
This file contains the declaration of a single structure containing the private
global variables used by the subsystem (see the section on globals below for
more details).
-=item foo.sym
+=item C<foo.sym>
This file (format and contents TBD) contains information about global symbols
associated with the subsystem, and may be used by scripts to auto-generate such
stuff as the include files mentioned above, linker map tables, documentation
-etc, based upon portability and extensibility requirements.
+etc., based upon portability and extensibility requirements.
-=item foo_bar.[ch] etc
+=item C<foo_bar.[ch]> etc.
All other source files associated with the subsystem will have the prefix foo_
@@ -626,7 +631,7 @@
=item Names of code entities
-Code entities such as variables, functions, macros etc (apart from strictly
+Code entities such as variables, functions, macros etc. (apart from strictly
local ones) should all follow these general guidelines.
=over 4
@@ -645,8 +650,8 @@
=item *
-All entities should be prefixed with the name of the subsystem they appear in,
-e.g. C<pmc_foo()>, C<struct io_bar>.
+All entities should be prefixed with the name of the subsystem in which they
+appear, e.g. C<pmc_foo()>, C<struct io_bar>.
=item *
@@ -707,8 +712,8 @@
=item *
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, e.g. C<PMC_valid_CLEARALL(foo)>
+should have C<_SETALL>, C<_CLEARALL>, C<_TESTALL> or C<_TESTANY> suffixes as
+appropriate, to indicate aggregate bits, e.g. C<PMC_valid_CLEARALL(foo)>.
=item *
@@ -719,7 +724,7 @@
A macro indicating the compilation 'location' should be prefixed with C<IN_>,
e.g. C<PERL_IN_CORE>, C<PERL_IN_PMC>, C<PERL_IN_X2P>. Individual include file
-visitations should be marked with C<PERL_IN_FOO_H> for file foo.h
+visitations should be marked with C<PERL_IN_FOO_H> for file C<foo.h>
=item *
@@ -750,12 +755,12 @@
least).
All global variables needed for the internal use of a particular subsystem
-should all be declared within a single struct called foo_globals for subsystem
-foo. This structure's declaration is placed in the file foo_globals.h. Then
-somewhere a single compound structure will be declared which has as members the
-individual structures from each subsystem. Instances of this structure are then
-defined as a one-off global variable, or as per-thread instances, or whatever
-is required.
+should all be declared within a single struct called C<foo_globals> for
+subsystem C<foo>. This structure's declaration is placed in the file
+C<foo_globals.h>. Then somewhere a single compound structure will be
+declared which has as members the individual structures from each subsystem.
+Instances of this structure are then defined as a one-off global variable,
+or as per-thread instances, or whatever is required.
[Actually, three separate structures may be required, for global,
per-interpreter and per-thread variables.]
@@ -792,7 +797,7 @@
=item Developer files
-Each source file (e.g. a F<foo.c> F<foo.h> pair), should contain inline POD
+Each source file (e.g. a F<foo.c>, F<foo.h> pair), should contain inline POD
documentation containing information on the implementation decisions associated
with the source file. (Note that this is in contrast to PDDs, which describe
design decisions). In addition, more discussive documentation can be placed in
@@ -839,8 +844,8 @@
=item SEE ALSO
-Links to pages and books that may contain useful info relevant to the stuff
-going on in the code - e.g. the book you stole the hash function from.
+Links to pages and books that may contain useful information relevant to the
+stuff going on in the code -- e.g. the book you stole the hash function from.
=back
@@ -893,7 +898,7 @@
=item General comments
While there is no need to go mad commenting every line of code, it is immensely
-helpful to provide a "running commentary" every 10 or so lines say; if nothing
+helpful to provide a "running commentary" every 10 lines or so if nothing
else, this makes it easy to quickly locate a specific chunk of code. Such
comments are particularly useful at the top of each major branch, e.g.
@@ -914,14 +919,15 @@
=head2 Extensibility
-If Perl 5 is anything to go by, the lifetime of Perl 6 will be at least seven
-years. During this period, the source code will undergo many major changes
-never envisaged by its original authors - cf threads, unicode in perl 5. To
-this end, your code should balance out the assumptions that make things
-possible, fast or small, with the assumptions that make it difficult to change
-things in future. This is especially important for parts of the code which are
-exposed through APIs - the requirements of src or binary compatibility for such
-things as extensions can make it very hard to change things later on.
+If Perl 5 is anything to go by, the lifetime of Perl 6 will be at least
+seven years. During this period, the source code will undergo many major
+changes never envisaged by its original authors -- c.f. threads, unicode in
+perl 5. To this end, your code should balance out the assumptions that make
+things possible, fast or small, with the assumptions that make it difficult
+to change things in future. This is especially important for parts of the
+code which are exposed through APIs -- the requirements of source or binary
+compatibility for such things as extensions can make it very hard to change
+things later on.
For example, if you define suitable macros to set/test flags in a struct, then
you can later add a second word of flags to the struct without breaking source
@@ -933,8 +939,8 @@
foo->flags |= (FOO_int_FLAG | FOO_num_FLAG | FOO_str_FLAG);
FOO_valid_value_SETALL(foo);
-Similarly, avoid using a char* (or {char*,length}) if it is feasible to later
-use a C<PMC *> at the same point: cf UTF-8 hash keys in Perl 5.
+Similarly, avoid using a C<char*> (or C<{char*,length}>) if it is feasible
+to later use a C<PMC *> at the same point: c.f. UTF-8 hash keys in Perl 5.
Of course, private code hidden behind an API can play more fast and loose than
code which gets exposed.
