I originally starting writing this as a bit of a joke, then I thought
perhaps I should submit it as a serious suggestion. Anyone violently
against or in favour? Is this even an issue that should go in a PDD?
Does anyone care? Should I return to my box now?

Dave M.

====================================

=head1 TITLE

Mandatory comments within Perl source code

=head1 VERSION

=head2 CURRENT

   Maintainer: Dave Mitchell <[EMAIL PROTECTED]>
   Class: Internals
   PDD Number: TBD 
   Version: 1
   Status: Proposed
   Last Modified: 17 February 2001
   PDD Format: 1
   Language: English

=head2 HISTORY

None. First version

=head1 CHANGES

None. First version

=head1 ABSTRACT

This RFC describes the minimum set of comments that B<must> be present in
every source file.

=head1 DESCRIPTION

One of the criticisms of Perl 5 is that it's source code is impenetrable
to newcomers, not least because of the lack often of comments within
the code. This document provides some minimum standards for adding
commentary to source files; code which does not follow these guidelines
should not be accepted into the main code stream(s).

Of course, you are allowed to add comments in addition to the ones
mandated here :-)


=head1 IMPLEMENTATION

=head2 Per-file comments

In addition to the copyright message and LOTR quote, each file should
have a comment at the top explaining the basic purpose of the file, eg

        /* pp_hot.c - like pp.c, this file contains functions that operate
         * on the contents of the stack (pp == 'push & pop'), but in this
         * case, frequently used ('hot') functions have been moved here
         * from pp.c to (hopefully) improve CPU cache hit rates.
         */

=head2 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 explaining their overall
purpose. (If there is only one section, then the per-file comment
already satisfies this requirement.)

        /* This section deals with 'arenas', which are chunks of SVs of
         * a particular type that are allocated in one go. Individual
         * requests can then be made to grab or release individual SVs.
         * For each type I<foo>, there is a global pointer called
         * I<PL_foo_root> which blah blah....
         */

=head2 Per-function and per-structure comments

Each function and structure should have at least a short one-line
comment explaining its purpose. Often this will be be little more than
expanding the acronym making up the function's name, with the wider
purpose already explained by the section comment; but sometimes more
explanation will be needed.

        /* return an Integer SV to its arena */

        STATIC void
        S_del_xiv(pTHX_ XPVIV *p)
        ...

=head2 Optimisations

Any code which is deliberately written in a strange way to make it run
faster should be flagged as such, in order to stop some shmuck trying
subsequently to replace it with something 'cleaner'.

        /* NB - this may look bizarre, but partial unrolling of the
         * loop makes the hash calculation a lot faster, at the expense
         * of slightly larger code. See http//.... for the full gory details.
         */ 


=head1 REFERENCES

The Perl 5 source :-)


Reply via email to