NAME

docs/pdds/pdd07_codingstd.pod - Conventions and Guidelines for Parrot Source Code

VERSION

$Revision$

ABSTRACT

This document describes the various rules, guidelines and advice for those wishing to contribute to the source code of Parrot, in such areas as code structure, naming conventions, comments etc.

DESCRIPTION

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. We don't intend to make the same mistake when writing Parrot. Hence this document.

We define three classes of conventions:

"must": Items labelled must are mandatory; and code will not be accepted (apart from in exceptional circumstances) unless it obeys them.
"should": Items labelled should are strong guidelines that should normally be followed unless there is a sensible reason to do otherwise.
"may": Items labelled may are tentative suggestions to be used at your discretion.

Note that since Parrot is substantially implemented in C, these rules apply to C language source code unless otherwise specified.

IMPLEMENTATION

Language Standards and Portability

C code must generally depend on only those language and library features specified by the ISO C89 standard.

In addition, C code may assume that any pointer value can be coerced to an integral type (no smaller than typedef INTVAL in Parrot), then back to its original type, without loss.

C code that makes assumptions beyond these must depend on the configuration system, either to not compile an entire non-portable source where it will not work, or to provide an appropriate #ifdef macro.

{{ TODO: Enumerate all other non-C89 assumptions that Parrot depends on. }}

Perl code must be written for Perl 5.6.1 and all later versions.

Perl code may use features not available in Perl 5.6.1 only if it is not vital to Parrot, and if it uses $^O and $] to degrade or fail gracefully when it is run where the features it depends on are not available.

Code Formatting

The following must apply:

Source line width is limited to 100 characters. Exceptions can be made for technical requirements, but not for style reasons. And please bear in mind that very long lines can be hard to read.

Indentation must consist only of spaces. (Tab characters just complicate things.)

C and Perl code must be indented four columns per nesting level.

Preprocessor #directives must be indented two columns per nesting level, with two exceptions: neither PARROT_IN_CORE nor the outermost _GUARD #ifdefs cause the level of indenting to increase.

Labels (including case labels) must be outdented two columns relative to the code they label.

Closing braces for control structures must line up vertically with the start of the control structures; e.g. } that closes an if must line up with the if.

Long lines, when split, must use at least one extra level of indentation on the continued line.

Cuddled elses are forbidden: i.e. avoid } else { .

The following should apply:

In function definitions, the function name must be on the left margin, with the return type on the previous line.

In function declarations (e.g. in header files), the function name must be on the same line as the return type.

Pointer types should be written with separation between the star and the base type, e.g. Interp *foo, but not e.g. <Interp* foo>.

To distinguish keywords from function calls visually, there should be at least one space between a C keyword and any subsequent open parenthesis, e.g. return (x+y)*2. There should be no space between a function name and the following open parenthesis, e.g. z = foo(x+y)*2

Use patterns of formatting to indicate patterns of semantics. Similar items should look similar, as the language permits. Note that some dimensions of similarity are incidental, not worth emphasizing; e.g. "these are all ints".

Binary operators (except . and ->) should have at least one space on either side; there should be no space between unary operators and their operands; parentheses should not have space immediately after the opening parenthesis nor immediately before the closing parenthesis; commas should have at least one space after, but not before; e.g.:

        x = (a-- + b) * f(c, d / e.f)

Use vertical alignment for clarity of parallelism. Compare this (bad):

     foo = 1 + 100;
     x = 100 + 1;
     whatever = 100 + 100;

... to this (good):

     foo      =   1 + 100;
     x        = 100 +   1;
     whatever = 100 + 100;

Do not routinely put single statements in statement blocks.

(Note that formatting consistency trumps this rule. For example, a long if/else if chain is easier to read if all (or none) of the conditional code is in blocks.)

Return values should not be parenthesized without need. It may be necessary to parenthesize a long return expression so that a smart editor will properly indent it.

When assigning inside a conditional, use extra parentheses, e.g. if (a && (b = c)) ... or if ((a = b)) ....

When splitting a long line at a binary operator (other than comma), the split should be before the operator, so that the continued line looks like one.

When splitting a long line inside parentheses (or brackets), the continuation should be indented to the right of the innermost unclosed punctuation, e.g.:

    z = foo(bar + baz(something_very_long_here
                       * something_else_very_long),
            corge);

Code Structure

The following must apply:

C code must use C-style comments only, i.e. /* comment */. (Not all C compilers handle C++-style comments.)

Structure types must have tags.

Functions must have prototypes in scope at the point of use. Prototypes for extern functions must appear only in header files. If static functions are defined before use, their definitions serve as prototypes.

Parameters in function prototypes must be named. These names should match the parameters in the function definition.

Variable names must be included for all function parameters in the function declarations.

Header files must be wrapped with guard macros to prevent header redefinition. The guard macro must begin with PARROT_, followed by unique and descriptive text identifying the header file (usually the directory path and filename,) and end with a _GUARD suffix. The matching #endif must have the guard macro name in a comment, to prevent confusion. For example, a file named parrot/foo.h might look like:

    #ifndef PARROT_FOO_H_GUARD
    #define PARROT_FOO_H_GUARD

    #include "parrot/config.h"
    #ifdef PARROT_HAS_FEATURE_FOO
    #  define FOO_TYPE bar
    typedef struct foo {
        ...
    } foo_t;
    #endif /* PARROT_HAS_FEATURE_FOO */

    #endif /* PARROT_FOO_H_GUARD */

The following should apply

Structure types should have typedefs with the same name as their tags, e.g.:

    typedef struct Foo {
        ...
    } Foo;

Avoid double negatives, e.g. #ifndef NO_FEATURE_FOO.

Do not compare directly against NULL, 0, or FALSE. Instead, write a boolean test, e.g. if (!foo) ....

(Note: PMC * values should be checked for nullity with the PMC_IS_NULL macro, unfortunately leading to violations of the double-negative rule.)

Avoid dependency on "FIXME" and "TODO" labels; if a bug must be fixed soon, use "XXX", else use the external bug tracking system.

Smart Editor Style Support

All developers using Emacs must ensure that their Emacs instances load the elisp source file editor/parrot.el before opening Parrot source files. See "README.pod" in editor for instructions.

All source files must end with an editor instruction coda:

C source files, and files largely consisting of C (e.g. yacc, lex, PMC, and opcode source files), must end with this coda:

   /*
    * Local variables:
    *   c-file-style: "parrot"
    * End:
    * vim: expandtab shiftwidth=4:
    */

Perl source files must end with this coda:

    # Local Variables:
    #   mode: cperl
    #   cperl-indent-level: 4
    #   fill-column: 100
    # End:
    # vim: expandtab shiftwidth=4:

Exception: Files with __END__ or __DATA__ blocks do not require the coda. This is at least until there is some consensus as to how solve the issue of using editor hints in files with such blocks.

PIR source files should end with this coda:

    # Local Variables:
    #   mode: pir
    #   fill-column: 100
    # End:
    # vim: expandtab shiftwidth=4:

{{ XXX - Proper formatting and syntax coloring of C code under Emacs requires that Emacs know about typedefs. We should provide a simple script to update a list of typedefs, and parrot.el should read it or contain it. }}

Portability

Parrot runs on many, many platforms, and will no doubt be ported to ever more bizarre and obscure ones over time. You should never assume an operating system, processor architecture, endian-ness, size of standard type, or anything else that varies from system to system.

Since most of Parrot's development uses GNU C, you might accidentally depend on a GNU feature without noticing. To avoid this, know what features of gcc are GNU extensions, and use them only when they're protected by #ifdefs.

Defensive Programming

Use Parrot data structures instead of C strings and arrays

C arrays, including strings, are very sharp tools without safety guards, and Parrot is a large program maintained by many people. Therefore:

Don't use a char * when a Parrot STRING would suffice. Don't use a C array when a Parrot array PMC would suffice. If do use a char * or C array, check and recheck your code for even the slightest possibility of buffer overflow or memory leak.

Note that efficiency of some low-level operations may be a reason to break this rule. Be prepared to justify your choices to a jury of your peers.

Pass only `unsigned char` to `isxxx()` and `toxxx()`

Pass only values in the range of unsigned char (and the special value -1, a.k.a. EOF) to the isxxx() and toxxx() library functions. Passing signed characters to these functions is a very common error and leads to incorrect behavior at best and crashes at worst. And under most of the compilers Parrot targets, char is signed.

The `const` keyword on arguments

Use the const keyword as often as possible on pointers. It lets the compiler know when you intend to modify the contents of something. For example, take this definition:

    int strlen(const char *p);

The const qualifier tells the compiler that the argument will not be modified. The compiler can then tell you that this is an uninitialized variable:

    char *p;
    int n = strlen(p);

Without the const, the compiler has to assume that strlen() is actually initializing the contents of p.

The `const` keyword on variables

If you're declaring a temporary pointer, declare it const, with the const to the right of the *, to indicate that the pointer should not be modified.

    Wango * const w = get_current_wango();
    w->min  = 0;
    w->max  = 14;
    w->name = "Ted";

This prevents you from modifying w inadvertantly.

    new_wango = w++; /* Error */

If you're not going to modify the target of the pointer, put a const to the left of the type, as in:

    const Wango * const w = get_current_wango();
    if (n < wango->min || n > wango->max) {
        /* do something */
    }

Localizing variables

Declare variables in the innermost scope possible.

    if (foo) {
        int i;
        for (i = 0; i < n; i++)
            do_something(i);
    }

Don't reuse unrelated variables. Localize as much as possible, even if the variables happen to have the same names.

    if (foo) {
        int i;
        for (i = 0; i < n; i++)
            do_something(i);
    }
    else {
        int i;
        for (i = 14; i > 0; i--)
            do_something_else(i * i);
    }

You could hoist the int i; outside the test, but then you'd have an i that's visible after it's used, which is confusing at best.

Subversion properties

svn:ignore

Sometimes new files will be created in the configuration and build process of Parrot. These files should not show up when checking the distribution with

    svn status

    perl tools/dev/manicheck.pl

The list of these ignore files can be set up with:

    svn propedit svn:ignore <PATH>

In order to keep the two different checks synchronized, the MANIFEST and MANIFEST.SKIP file should be regenerated with:

    perl tools/dev/mk_manifest_and_skip.pl

svn:mime-type

The svn:mime-type property must be set to text/plain for all test files, and may be set to text/plain for other source code files in the repository. Using auto-props, Subversion can automatically set this property for you on test files. To enable this option, add the following to your ~/.subversion/config:

    [miscellany]
    enable-auto-props = yes
    [auto-props]
    *.t = svn:mime-type=text/plain

svn:keywords

The svn:keywords property should be set to:

    Author Date Id Revision

on each file with a mime-type of text/plain. Do this with the command:

    svn propset svn:keywords "Author Date Id Revision" <filename>

The t/distro/file_metadata.t test checks that the files needing this property have it set.

svn:eol-style

The svn:eol-style property makes sure that whenever a file is checked out of subversion it has the correct end-of-line characters appropriate for the given platform. Therefore, most files should have their svn:eol-style property set to native. However, this is not true for all files. Some input files to tests (such as the *.input and *.output files for PIR tests) need to have LF as their svn:eol-style property. The current list of such files is described in t/distro/file_metadata.t.

Set the svn:eol-style property to native with the command:

    svn propset svn:eol-style "native" <filename>

Set the svn:eol-style property to LF with the command:

    svn propset svn:eol-style "LF" <filename>

The t/distro/file_metadata.t test checks that the files needing this property have it set.

CHIP HAS EDITED THIS FAR INTO THE FILE

  +-------------------------------------------------------+
    Everything below this point must still be reviewed
  +-------------------------------------------------------+

Naming conventions

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 subsystem will be assigned a short nickname, e.g. pmc, gc, 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.
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 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 to them or which do the preprocessing - e.g. a script foo.SH might read foo.TEMPLATE and output foo.c.; The characters making up filenames must be chosen from the ASCII set A-Z,a-z,0-9 plus .-_; An underscore should be used to separate words rather than a hyphen (-). A file should not normally have more than a single '.' in it, and this should be used to denote a suffix of some description. The filename must still be unique if the main part is truncated to 8 characters and any suffix truncated to 3 characters. Ideally, filenames should restricted to 8.3 in the first place, but this is not essential.; Each subsystem 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 core, as well as to extensions and embeddings.
Header Files: All .h files should include the following "guards" to prevent multiple-inclusion:
Names of code entities: Code entities such as variables, functions, macros etc (apart from strictly local ones) should all follow these general guidelines.
Global Variables: Global variables must never be accessed directly outside the subsystem in which they are used. Some other method, such as accessor functions, must be provided by that subsystem's API. (For efficiency the 'accessor functions' may occasionally actually be macros, but then the rule still applies in spirit at 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.; [Actually, three separate structures may be required, for global, 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). So we might for example have the following macros:

Code comments

The importance of good code documentation cannot be stressed enough. To make your code understandable by others (and indeed by yourself when you come to make changes a year later :-), the following conventions apply to all source files.

Developer files: Each source file (e.g. a foo.c 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 *.dev files in the docs/dev directory. This is the place for mini-essays on how to avoid overflows in unsigned arithmetic, or on the pros and cons of differing hash algorithms, and why the current one was chosen, and how it works.; In principle, someone coming to a particular source file for the first time should be able to read the inline documentation file and gain an immediate overview of what the source file is for, the algorithms it implements, etc.; The POD documentation should follow the standard POD layout:
Per-section comments: If there is a collection of functions, structures or whatever which are grouped together and have a common theme or purpose, there should be a general comment at the start of the section briefly explaining their overall purpose. (Detailed essays should be left to the developer file). If there is really only one section, then the top-of-file comment already satisfies this requirement.
Per-entity comments: Every non-local named entity, be it a function, variable, structure, macro or whatever, must have an accompanying comment explaining its purpose. This comment must be in the special format described below, in order to allow automatic extraction by tools - for example, to generate per API man pages, perldoc -f style utilities and so on.; Often the comment need only be a single line explaining its purpose, but sometimes more explanation may be needed. For example, "return an Integer Foo to its allocation pool" may be enough to demystify the function del_I_foo(); Each comment should be of the form; This inline POD documentation is parsed to HTML by running:
Optimizations: Whenever code has deliberately been written in an odd way for performance reasons, you should point this out - if nothing else, to avoid some poor schmuck trying subsequently to replace it with something 'cleaner'.
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 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.

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.

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 compatibility. (Although you might still break binary compatibility if you're not careful.) Of the following two methods of setting a common combination of flags, the second doesn't assume that all the flags are contained within a single field:

    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 PMC * at the same point: cf 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.

Performance

We want Perl to be fast. Very fast. But we also want it to be portable and extensible. Based on the 90/10 principle, (or 80/20, or 95/5, depending on who you speak to), most performance is gained or lost in a few small but critical areas of code. Concentrate your optimization efforts there.

Note that the most overwhelmingly important factor in performance is in choosing the correct algorithms and data structures in the first place. Any subsequent tweaking of code is secondary to this. Also, any tweaking that is done should as far as possible be platform independent, or at least likely to cause speed-ups in a wide variety of environments, and do no harm elsewhere. Only in exceptional circumstances should assembly ever even be considered, and then only if generic fallback code is made available that can still be used by all other non-optimized platforms.

Probably the dominant factor (circa 2001) that effects processor performance is the cache. Processor clock rates have increased far in excess of main memory access rates, and the only way for the processor to proceed without stalling is for most of the data items it needs to be found to hand in the cache. It is reckoned that even a 2% cache miss rate can cause a slowdown in the region of 50%. It is for this reason that algorithms and data structures must be designed to be 'cache-friendly'.

A typical cache may have a block size of anywhere between 4 and 256 bytes. When a program attempts to read a word from memory and the word is already in the cache, then processing continues unaffected. Otherwise, the processor is typically stalled while a whole contiguous chunk of main memory is read in and stored in a cache block. Thus, after incurring the initial time penalty, you then get all the memory adjacent to the initially read data item for free. Algorithms that make use of this fact can experience quite dramatic speedups. For example, the following pathological code ran four times faster on my machine by simply swapping i and j.

    int a[1000][1000];

    ... (a gets populated) ...

    int i,j,k;
    for (i=0; i<1000; i++) {
        for (j=0; j<1000; j++) {
            k += a[j][i];
        }
    }

This all boils down to: keep things near to each other that get accessed at around the same time. (This is why the important optimizations occur in data structure and algorithm design rather than in the detail of the code.) This rule applies both to the layout of different objects relative to each other, and to the relative positioning of individual fields within a single structure.

If you do put an optimization in, time it on as many architectures as you can, and be suspicious of it if it slows down on any of them! Perhaps it will be slow on other architectures too (current and future). Perhaps it wasn't so clever after all? If the optimization is platform specific, you should probably put it in a platform-specific function in a platform-specific file, rather than cluttering the main source with zillions of #ifdefs.

And remember to document it.

Loosely speaking, Perl tends to optimize for speed rather than space, so you may want to code for speed first, then tweak to reclaim some space while not affecting performance.

EXEMPTIONS

Not all files can strictly fall under these guidelines as they are automatically generated by other tools, or are external files included in the Parrot repository for convenience. Such files include the C header and source files automatically generated by (f)lex and yacc/bison, and some of the Perl modules under the lib/ directory.

To exempt a file (or directory of files) from checking by the coding standards tests, one must edit the appropriate exemption list within lib/Parrot/Distribution.pm (in either of the methods is_c_exemption() or is_perl_exemption()). One can use wildcards in the list to exempt, for example, all files under a given directory.

REFERENCES

The section on coding style is based on Perl 5's Porting/patching.pod by Daniel Grisinger. The section on naming conventions grew from some suggestions by Paolo Molaro <lupus@lettere.unipd.it>. Other snippets came from various P5Pers.

parrotcode: Conventions and Guidelines for Parrot Source
Contents \| Documentation