Paul Cochrane wrote:
=item *
Under "Language Standards and Portability" there is the todo item:
{{ RT#45359: Enumerate all other non-C89 assumptions that Parrot
depends on. }}
Currently we have such assumptions as:
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.
Are there any others?
There aren't currently any other system-wide assumptions recognized by
all Parrot developers, so delete the note and close the ticket. As we
encounter sections of the code that don't follow the C89 standard, we
can decide on a case-by-case basis whether the code should be
standardized or the coding standards changed. (Generally the former.)
The same principle applies to new code.
=item *
Under "Code Structure" there is the comment:
Avoid dependency on "FIXME" and "TODO" labels; if a bug must be fixed soon,
use "XXX", else use the external bug tracking system.
Shouldn't we put everything into the bug tracking system? There are
so many XXX items sitting in the code currently (I've converted many
into RT tickets, but there are hundreds to go) and they've been in
there quite a while. Is it a good idea to make a blanket "put
everything into RT" policy (and isn't that the current policy anyway)?
Let's say "if a bug must be fixed soon, use XXX and the external bug
tracking system." That is, every XXX should have an RT ticket number
next to it.
=item *
Chip only got so far through the coding standards PDD before other
things in his life took over (which I hope are now going better!).
Therefore much of the rest of the document (after "Naming
Conventions") needs to be discussed and decided upon.
I just flagged my ticket to review pdd07 with a high priority.
=item Subsystems and APIs
The C<misc> subsystem is mentioned in this section. It doesn't seem
to appear anywhere. Do we need such a subsystem? Is there a list of
known subsystems anywhere?
The only place subsystem naming is used is in the naming of directories
and files in src/. This is one of those coding standards that seemed
like a good idea at the time, but didn't really turn out to be terribly
useful. Delete at least the last sentence of that section, perhaps even
the whole section.
=item Filenames
It's mentioned that ideally filenames should be restricted to 8.3
format. Should this really be the case? Windows has handled longer
filenames for a long time now (and so have unix-based systems); so do
we really need to worry? This is probably only a recommendation
anyway.
Various platforms have various restrictions. The 8.3 format is just a
safe minimum that we know will work on all platforms. If someone wants
to do the work of detailing our major target platforms and likely target
platforms and propose a less restrictive minimum that still works on
those platforms, I'd approve it. perlport.pod is a good resource while
working on the list, but something more systematic (perhaps a
spreadsheet) would be more ideal.
=item Macro names
The document mentions macro names such as C<PERL_IN_CORE>,
C<PERL_IN_FOO>, and C<PERL_USE_STDIO>. I'm guessing this is as a
result of copy and paste from an original Perl 5 document, so
shouldn't these macro names be C<PARROT_IN_CORE>, C<PARROT_IN_FOO> and
C<PARROT_USE_STDIO>?
Yes.
A related question: shouldn't the text (mentioned later under "Global
variables")
# define GLOBALS_BASE (Perl_globals)
really be
# define GLOBALS_BASE (Parrot_globals)
Yes.
=item foo.sym file format
It is mentioned that the format and contents of the C<foo.sym> file
(for the Parrot subsystem C<foo>) need to be decided.
The .sym files are a Perl convention that Parrot isn't using. Delete it
from the coding conventions.
=item Per-entity comments
I've noticed in the source lots of C<FUNCDOC> sections in C-language
code. Shouldn't this just be plain pod as mentioned in PDD07? This
would mean that more docs are picked up when we run C<make html>,
isn't that right?
Yes, FUNCDOC is deprecated, it just needs a cage cleaner to go through
and edit it out.
=item Performance
There's a mention in this section about what the dominant factor in
2001 is for processor performance. Being at least 6 years away from
that point, what's changed? Is cache still the biggest factor for
performance hits/gains? Clock rates haven't increased that much of
late (the docs currently mention that they've been going up a lot) and
multi-processor systems seem to be the "way of the future" currently
(I saw a talk recently where a guy was talking about commodity systems
with 64 or 128 cores in about 5 years). So is it worth noting such
stuff here? Are there any other performance issues we should discuss
in this section?
Most of the Performance section is inappropriate for a design document
on coding standards (though nice for a general article on optimization).
I've edited it down.
Again, if you got to here, well done! And thanks!
And thank you!
Allison
