<commit_before># Copyright (C) 2001-2006, The Perl Foundation.
# $Id$

=head1 NAME

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

=head1 VERSION

$Revision$

=head1 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.

=head1 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:

=over 4

=item I<"must">

Items labelled I<must> are mandatory; and code will not be accepted (apart
from in exceptional circumstances) unless it obeys them.

=item I<"should">

Items labelled I<should> are strong guidelines that should normally be
followed unless there is a sensible reason to do otherwise.

=item I<"may">

Items labelled I<may> are tentative suggestions to be used at your discretion.

=back

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

=head1 IMPLEMENTATION


=head2 Language Standards and Portability

=over 4

=item *

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 C<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. }}

=item *

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 C<$^O> and C<$]> to degrade or fail gracefully when
it is run where the features it depends on are not available.

=back


=head2 Code Formatting

The following I<must> apply:

=over 4

=item *

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 I<can> be hard to read.

=item *

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

=item *

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

=item *

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.

=item *

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

=item *

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

=item *

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

=item *

Cuddled C<else>s are forbidden: i.e. avoid  C<} else {> .

=back


The following I<should> apply:

=over 4

=item *

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

=item *

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

=item *

There should be one space between C keywords and following open parentheses,
e.g. C<return (x+y)*2>.

There should be no space between function names and following open parentheses,
e.g. C<z = foo(x+y)*2>

=item *

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".

=item *

Binary operators (except C<.> and C<< -> >>) 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)

=item *

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;

=item *

Do not routinely put single statements in statement blocks.

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

=item *

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.

{{ TODO: Modify parrot.el so this rule is no longer required. }}

=item *

When assignming inside a conditional, use extra parentheses,
e.g. C<if (a && (b = c)) ...> or C<if ((a = b)) ...>.

=item *

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

=item *

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);

=back


=head2 Code Structure

The following I<must> apply:

=over 4

=item *
<commit_msg>[PDD07]: fix typo<commit_after># Copyright (C) 2001-2006, The Perl Foundation.
# $Id$

=head1 NAME

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

=head1 VERSION

$Revision$

=head1 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.

=head1 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:

=over 4

=item I<"must">

Items labelled I<must> are mandatory; and code will not be accepted (apart
from in exceptional circumstances) unless it obeys them.

=item I<"should">

Items labelled I<should> are strong guidelines that should normally be
followed unless there is a sensible reason to do otherwise.

=item I<"may">

Items labelled I<may> are tentative suggestions to be used at your discretion.

=back

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

=head1 IMPLEMENTATION


=head2 Language Standards and Portability

=over 4

=item *

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 C<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. }}

=item *

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 C<$^O> and C<$]> to degrade or fail gracefully when
it is run where the features it depends on are not available.

=back


=head2 Code Formatting

The following I<must> apply:

=over 4

=item *

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 I<can> be hard to read.

=item *

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

=item *

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

=item *

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.

=item *

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

=item *

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

=item *

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

=item *

Cuddled C<else>s are forbidden: i.e. avoid  C<} else {> .

=back


The following I<should> apply:

=over 4

=item *

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

=item *

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

=item *

There should be one space between C keywords and following open parentheses,
e.g. C<return (x+y)*2>.

There should be no space between function names and following open parentheses,
e.g. C<z = foo(x+y)*2>

=item *

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".

=item *

Binary operators (except C<.> and C<< -> >>) 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)

=item *

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;

=item *

Do not routinely put single statements in statement blocks.

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

=item *

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.

{{ TODO: Modify parrot.el so this rule is no longer required. }}

=item *

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

=item *

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

=item *

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);

=back


=head2 Code Structure

The following I<must> apply:

=over 4

=item *

{'fraction_non_alphanumeric': 0.06435517970401691, 'fraction_numerical': 0.01150105708245243, 'mean_word_length': 3.7859166329421288, 'pattern_counts': {'":': 0, '<': 59, '<?xml version=': 0, '>': 61, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6485409', 'n_tokens_mistral': 3545, 'n_tokens_neox': 3291, 'n_words': 1788}