Just some brief comments... $0.02 or some such. :)
-R
Quoting Dave Mitchell <[EMAIL PROTECTED]>:
> =item *
>
> "K&R" style for indenting control constructs: ie the closing C<}>
> should
> line up with the opening C<if> etc.
You should provide a short example here - K&R has lots of nasties, you want to
be explicit.
> =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.
Examples too :) I'm pretty sure I know what you mean, but might as well make sure.
> =item *
>
> Mark places that need to be revisited with XXX (and preferably your
> initials too), and revisit often!
How about something a little more explicit than XXX, like TODO or FIXME?
> =item *
>
> In function definitions, the name starts in column 0, with the
> return type on the previous line
Eww. Why do we want this again?
> The top-level structure of the Perl source tarball should be as
> follows:
>
> /README, etc a few top-level documents
> /doc/ Assorted miscellaneous documentation
> /pdd/ The current PDDs
> /perl/ The source code for Perl itself
> /perl/os/foo/ OS-specific source code for operating system foo
Why is perl a second class citzen in the Perl source tarball? Why not just /src/ ?
/perl/ is somewhat confusing as well, sounds like where perl code should live.
> /lib/ perl modules ready for installation
> /ext/ perl modules that need compiling
Do these really need to be seperate? Would it simplify things to have them
together? If it's ready for installation, you just don't do anything to it.
> =item *
>
> Macros should
There doesn't seem to be anything in here about avoiding macroitis (a la perl5),
or organization of macros.
> =item Developer files
>
> For each source file (eg a F<foo.c> F<foo.h> pair), there should be an
> accompanying developer file called F<foo.dev>. This text file contains
> documentation on all the implementation decisions associated with the
> source file. (Note that this is in contrast to PDDs, which describe
> design decisions). 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 F<.dev> file and gain an immediate
> overview of what the source file is for, the algorithms it implements,
> etc.
This is one more file to get lost or confused or forgotten about. Why not put
this stuff in the .c or .h file? If you're concerned about verbosity of
comments, why not define a footnote/reference syntax for comments (something
simple like [1] ) and put these mini-essays at the bottom of the file.
>
> Currently no particular format or structure is imposed on the
> developer
> file, but it should have as a minimum the following sections:
Reading on.. all these things should be in the source file.
> Explain the purpose of the source file.
> =item Data structures and algorithms
> Explain how it all works.
> =item History
> =item Notes
> =item References
> =item Top-of-file comments
>
> In addition to the copyright message and optional quote, each source
> file must have a short 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.
> */
Reading on further, this is duplicated information from above.
> /*=for api apiname entityname[,entityname..] flags ....(TBC)....
> comments....
> */
This is perl5ish syntax. Has there been thought about a different syntax here?
Seems like it might make sense.
Also, I see pod here, but nowhere else in the above sections. It should be all
POD or not POD.
> should be used over a bare char * whenever possible. Ideally there
> should
> be no char * in the source anywhere, and no use of C's standard string
> library.
Isn't this a little overzealous? I know there are differences between
implementations of the standard string library, but there _is_ a standard that
should be mostly safe to use.
