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