Missing tags and bad indents.
Index: pdds/pdd07_codingstd.pod
===================================================================
RCS file: /home/perlcvs/parrot/docs/pdds/pdd07_codingstd.pod,v
retrieving revision 1.2
diff -u -r1.2 pdd07_codingstd.pod
--- pdds/pdd07_codingstd.pod 4 Mar 2002 02:30:23 -0000 1.2
+++ pdds/pdd07_codingstd.pod 22 Mar 2002 14:50:18 -0000
@@ -31,7 +31,7 @@
=head1 DESCRIPTION
-One of the criticisms of Perl 5 is that it's source code is
+One of the criticisms of Perl 5 is that its source code is
impenetrable to newcomers, due to such things as inconsistent or
obscure variable naming conventions, lack of comments in the source
code, and so on. Hence this document.
@@ -40,8 +40,8 @@
mandatory, and code will not be accepted (apart from in exceptional
circumstances) unless it follows these rules. Those that say I<should>
are strong guidelines that should normally be be followed unless there
-is a sensible reason to do otherwise. Finally, where it says I<may>,
-this is tentative suggestion to be used at your discretion.
+is a sensible reason to do otherwise. Finally, those that say I<may>,
+are tentative suggestions to be used at your discretion.
Note this this particular PDD makes some recommendations that are
specific to the C programming language. This does not preclude Perl
@@ -58,7 +58,7 @@
=item *
-4-wide indents for code and 2-wide indents for nested CPP #directives.
+4 column indents for code and 2 column indents for nested CPP #directives.
All indentation must consist of spaces, no tabs (for ease of patching).
To ensure that tabs aren't inadvertently used for indentation, the following
@@ -91,12 +91,12 @@
=item *
-When a conditional spans multiple lines, the opening brace must line up
-with the "if" or "while", or be at the end-of-line otherwise.
+When a conditional spans multiple lines, the opening C<{> must line up
+with the C<if> or C<while>, or be at the end-of-line otherwise.
=item *
-Uncuddled elses: ie avoid C<} else {>
+Uncuddled C<else>s: ie avoid C<} else {>
=item *
@@ -110,7 +110,7 @@
=item *
In function definitions, the name starts in column 0, with the
-return type on the previous line
+return type on the previous line.
=item *
@@ -120,12 +120,13 @@
=item *
Variable names should be included for all function parameters in the
-function declarations.
+function declarations. These names should match the parameters in the
+function definition.
=item *
-Single space after keywords that are followed by parens, eg
-C<return (x+y)*2>, but no space between function name and following paren,
+Single space after keywords that are followed by C<()>, eg
+C<return (x+y)*2>, but no space between function name and following C<()>,
eg C<z = foo(x+y)*2>
=back
@@ -157,7 +158,7 @@
=item *
-binary operators should have a space on either side; parentheses should
+Binary operators should have a space on either side; parentheses should
not have space immediately after the opening paren nor immediately before
the closing paren, commas should have space after but not before, eg
@@ -175,13 +176,11 @@
with one extra indent:
do_arbitrary_function(
- list_of_parameters_with_long_names, or_complex_subexpression(
- of_more_params, or_expressions + 1
- )
+ list_of_parameters_with_long_names, or_complex_subexpression(
+ of_more_params, or_expressions + 1
+ )
);
-
-
=back
To enforce the spacing, indenting, and bracing guidelines mentioned
@@ -232,7 +231,7 @@
Please note that it is also necessary to include all typedef types
with the "-T" option to ensure that everything is formatted properly.
-A script (run_indent.pl) is be provided which runs indent properly for
+A script (F<run_indent.pl>) is provided which runs F<indent> properly
automatically.
=head2 Naming conventions
@@ -243,18 +242,18 @@
Perl core will be split into a number of subsystems, each with an
associated API. For the purposes of naming files, data structures, etc,
-each subsystem will be assigned a short nickname, eg pmc, gc, io. All
-code within the core will belong to a subsystem; miscellaneous code
+each subsystem will be assigned a short nickname, eg 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
-misc.
+I<misc>.
=item Filenames
Filenames must be assumed to be case-insensitive, in the sense that
-that you may not have two different files called Foo and foo. Normal
+that you may not have two different files called F<Foo> and F<foo>. Normal
source-code filenames should be all lower-case; filenames with
upper-case letters in them are reserved for notice-me-first files such
-as README, and for files which need some sort of pre-processing applied
+as F<README>, and for files which need some sort of pre-processing applied
to them or which do the preprocessing - eg a script F<foo.SH> might
read F<foo.TEMPLATE> and output F<foo.c>.
@@ -269,7 +268,6 @@
should restricted to 8.3 in the first place, but 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 - present an opaque interface to all other subsystems within the
@@ -284,13 +282,13 @@
the API to include different or extra functionality when used by other
parts of the core, compared with its use in extensions and embeddings.
In this case, the extra stuff within the file is enabled by testing for
-the macro PERL_IN_CORE.
+the macro C<PERL_IN_CORE>.
=item 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 defines the macro PERL_IN_FOO so that code knows when it is
+This file defines the macro C<PERL_IN_FOO> so that code knows when it is
being used within that subsystem. The file will also contain all the
'convenience' macros used to define shorter working names for functions
without the perl prefix (see below).
@@ -339,14 +337,14 @@
All .h files should include the following "guards" to prevent
multiple-inclusion:
- /* file header comments */
-
- #if !defined(PARROT_<FILENAME>_H_GUARD)
- #define PARROT_<FILENAME>_H_GUARD
-
- /* body of file */
-
- #endif /* PARROT_<FILENAME>_H_GUARD */
+ /* file header comments */
+
+ #if !defined(PARROT_<FILENAME>_H_GUARD)
+ #define PARROT_<FILENAME>_H_GUARD
+
+ /* body of file */
+
+ #endif /* PARROT_<FILENAME>_H_GUARD */
=item Names of code entities
@@ -394,7 +392,7 @@
=item *
-structure elements should be all lower-case, and the first component of
+Structure elements should be all lower-case, and the first component of
the name should incorporate the structure's name or an abbreviation of it.
=item *
@@ -499,7 +497,7 @@
per-interpreter and per-thread variables.]
Within an individual subsystem, macros are defined for each global
-variable of the form GLOBAL_foo (the name being deliberately clunky).
+variable of the form C<GLOBAL_foo> (the name being deliberately clunky).
So we might for example have the following macros:
/* perl_core.h or similar */
@@ -629,7 +627,6 @@
TBC ...
-
=item Optimisations
Whenever code has deliberately been written in an odd way for
@@ -669,7 +666,7 @@
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
+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
@@ -757,9 +754,9 @@
int i,j,k;
for (i=0; i<1000; i++) {
- for (j=0; j<1000; j++) {
- k += a[j][i];
- }
+ for (j=0; j<1000; j++) {
+ k += a[j][i];
+ }
}
This all boils down to: keep things near to each other that get
--
Bryan C. Warnock
[EMAIL PROTECTED]
