Re: Final, no really, Final draft: Conventions and Guidelines for Perl Source Code
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 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, etca 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 F pair), there should be an
> accompanying developer file called F. 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.
Re: Will subroutine signatures apply to methods in Perl6
> "DC" == Damian Conway <[EMAIL PROTECTED]> writes: DC> One might also envisage a C pragma to require DC> that all lexicals be typed. do you mean lexical params in a sub signature? or all lexicals in the current scope which contains the pragma? required typing for all lexicals feels too strong. many lexicals are just ordinary scalars and don't type well unless we require an int/string/float/ref type. what about making that mean that any scalar being assigned a method call (compile time checked only), must have a type? it would not be too broad and should be simple to check and it has useful behavior. use strict 'typing' ; my $foo = Dog.new() ; that fails at compile time. my Dog $spot = Dog.new() ; that is ok. my Canine $spot = Dog.new() ; that is ok if Dog ISA Canine. $spot could be assigned a Dog or a Cat my $foo = foo() ; is fine too, since no compile time detection of OO values is made. uri -- Uri Guttman - [EMAIL PROTECTED] -- http://www.sysarch.com SYStems ARCHitecture and Stem Development -- http://www.stemsystems.com Search or Offer Perl Jobs -- http://jobs.perl.org
Re: Will subroutine signatures apply to methods in Perl6
> "BD" == Brent Dax <[EMAIL PROTECTED]> writes: BD> # From: Uri Guttman [mailto:[EMAIL PROTECTED]] BD> # use strict 'typing' ; BD> # BD> # my $foo = Dog.new() ; BD> # BD> # that fails at compile time. BD> # BD> # my Dog $spot = Dog.new() ; BD> # BD> # that is ok. BD> # BD> # my Canine $spot = Dog.new() ; BD> # BD> # that is ok if Dog ISA Canine. $spot could be assigned a Dog or a Cat BD> # BD> # my $foo = foo() ; BD> # BD> # is fine too, since no compile time detection of OO values is made. BD> Two other possibilities: BD> 1. Typing is required on variables which method calls are invoked on: BD> use strict 'typing';#don't look at the keyboard! :^) BD> my Dog $spot=Dog.new; #ok BD> my Dog $fido=new Dog; #ok (indirect-object is staying, right?) BD> my $rex=Dog.new;#ok at this point... BD> $spot.bark(); #ok BD> $fido.bark(); #ok BD> $rex.bark();#ERROR: $rex isn't declared to hold an object is that a compile time or runtime error? i don't think you can make it compile time since $rex can be assigned a real object and still call the bark method. BD> 2. A 'normal' type: BD> use strict 'typing'; BD> my Dog $spot=Dog.new; #ok BD> my $foo="bar"; #bad--no type on $foo BD> my val $baz="quux"; #ok BD> I'm not necessarily suggesting 'val' as a type, however--that's just a BD> placeholder for whatever we would choose. i don't like that. plain perl scalars should always be allowed even when while odd pragmata are in effect. BD> I don't see this as being one of the 'normal' strictures--this BD> would be in the @EXPORT_OK array, not @EXPORT (if strict used BD> Exporter, that is). You'd have to turn it on explicitly. if it has the meaning i proposed, it could be under the default set in use strict. but it deosn't have to be. BD> Could we use this so that we don't have to use 'ref' (or its moral BD> equivalent) in method lookups? In other words, if $spot is declared to BD> hold a Dog, can we assume that it does, thus skipping the check with BD> 'ref' normally used for method dispatch? Would this even buy us BD> anything? Why am I asking myself these questions? Why are the BD> orderlies putting me in a white truck? no, that won't work. you can always bypass that at runtime in too many ways. as damian stated, runtime checks for objects are always in effect. if a method isn't found or handled by AUTOLOAD or something it is fatal (unless caught, of course). the method itself will always need to check its arguments if it cares about whether a class or object is the invocant (i like that word. thanx, damian!). uri -- Uri Guttman - [EMAIL PROTECTED] -- http://www.sysarch.com SYStems ARCHitecture and Stem Development -- http://www.stemsystems.com Search or Offer Perl Jobs -- http://jobs.perl.org
Re: Will subroutine signatures apply to methods in Perl6
> "BD" == Brent Dax <[EMAIL PROTECTED]> writes: BD> # BD> my $rex=Dog.new;#ok at BD> # this point... BD> # BD> # BD> $spot.bark(); #ok BD> # BD> $fido.bark(); #ok BD> # BD> $rex.bark();#ERROR: $rex BD> # isn't declared to hold an object BD> # BD> # is that a compile time or runtime error? i don't think you can make it BD> # compile time since $rex can be assigned a real object and BD> # still call the BD> # bark method. BD> Compile-time error. $rex was assigned a real object with Dog.new; BD> however, $rex wasn't _declared_ to be holding an object of any kind. BD> Thus, we can say at compile time that $rex can't bark since $rex isn't BD> supposed to have an object in it. then it should be a compile time error at the assignment to $rex and not later. you can't trace $rex at compile time to see what kind of object (if any) was assigned to it. so the illegal method call can't (easily) be detected at compile time. it has to be a runtime error. the assignment can be detected at compile time. what that means is that objects can only be assigned to scalars that are declared to be that type. i don't think that is needed for plain scalars though. BD> # BD> 2. A 'normal' type: BD> # BD> # BD> use strict 'typing'; BD> # BD> my Dog $spot=Dog.new; #ok BD> # BD> my $foo="bar"; #bad--no type on $foo BD> # BD> my val $baz="quux"; #ok BD> # BD> # BD> I'm not necessarily suggesting 'val' as a type, BD> # however--that's just a BD> # BD> placeholder for whatever we would choose. BD> # BD> # i don't like that. plain perl scalars should always be BD> # allowed even when BD> # while odd pragmata are in effect. BD> OTOH, we did invoke strict 'typing' so we would need to give types. It BD> kinda makes sense that you would need to specify a normal type, so you BD> don't accidentally forget to put a type in when you meant to. but types on all scalars is too much. making it types only on scalars that directly get assigned objects is ok. BD> # no, that won't work. you can always bypass that at runtime in too many BD> # ways. as damian stated, runtime checks for objects are always in BD> # effect. if a method isn't found or handled by AUTOLOAD or something it BD> # is fatal (unless caught, of course). the method itself will BD> # always need BD> # to check its arguments if it cares about whether a class or object is BD> # the invocant (i like that word. thanx, damian!). BD> I'm not sure if you understood what I meant there. I meant that, BD> if we know $spot is supposed to have a Dog in it, can we avoid BD> checking if it really does (at least some of the time) and maybe BD> shuck some overhead by doing so? Perhaps we only check after each BD> assignment to $spot, and when we check we set a flag saying that BD> it's already been typechecked so we don't have to do it again. BD> Whatever, methinks I may optimizing too early. We all know what BD> Knuth says about that. i agree with knuth here. :) and i understood what you meant. i was saying that it is the method sub itself that worries about how it gets called. and since the compiler can't track how a given object is assigned to a scalar, it can't make sure a method ALWAYS gets called correctly. you can always break method calls with a fully qualified sub call and then the method should still work if it is passed decent params. you seem to be conflating what can and should be done at compile time and at runtime. perl has so many runtime backdoors, that you can't ever guard a method and assure (at compile time) it will always be called correctly. so what our goal here is to allow stronger (or any!) compile time typing and checking in relatively normal (as other languages see it) cases with better sub and method signatures. any of these checks can so easily be circumvented that method writing should still be as defensive as they are (or should be) now. uri -- Uri Guttman - [EMAIL PROTECTED] -- http://www.sysarch.com SYStems ARCHitecture and Stem Development -- http://www.stemsystems.com Search or Offer Perl Jobs -- http://jobs.perl.org
Re: Perl 6 modules plan
I just subscribed, so forgive me if this has been covered before (I haven't read all of the archives yet) STYLE: > There should be tools, guidelines and processes to assist authors in writing > quality modules. See also [EMAIL PROTECTED] > Specifically: > Style guide > Naming guidelines I know this is mostly referring to entire modules, but I'd like to see some guidelines in the area of APIs, from method naming conventions all the way up to some "best practices" on the APIs themselves. Perl 5 modules are all over the place in terms of naming: MyFunc(), myMethod(), my_method(), get_value(), Value(), LoadValue(), setValue(), etc. etc. If you ask any Java programmer which is "correct", myJavaMethod() or My_Java_Method(), I think you'll get a straight answer. Same deal with C or even C++, for the most part. Ask a Perl programmer and you'll likely span the entire range of possibly API styles and philosophies. We need to make some decisions. But no B&D "rules" here, just "guidelines." VERSIONING: I mentioned this on another list, and I thought I'd bring it up here as well. I think NeXT-style "bundles" offer an interesting solution for keeping several versions of a single library installed at the same time, with well-defined major/minor version compatibility rules. This functionality becomes even more important with the proposed ability to specify modules by version (or version range, etc.) More information on bundles is available at Apple's web site. I think there are some ideas worth stealing here: http://gemma.apple.com/techpubs/macosx/Essentials/SystemOverview/Bundles/ HIERARCHY: As was pointed out earlier, we do need a real, planned hierarchy to avoid Time/Date and WWW/Web/HTML/CGI-type messes. Standards, standards, standards! (Easy for me to type, I know... ;) I'll also put in my vote for "deep" hierarchies. No, not: Universe::SolarSystem::Earth::NorthAmerica::US::MA::Newton::Person But two, three, or even four levels is not too severe, IMO, and will be necessary in the long run anyway. Individual "module distributions" can retain "shorter" names, but the individual modules that make up a distribution should be named without too much worry about namespace depth. To use the previously maligned Net:: prefix as an example, I really don't think this is all that bad: cpan> install Net::HTTP installing Net::HTTP::Message installing Net::HTTP::Request installing Net::HTTP::Response installing Net::HTTP::Headers installing Net::HTTP::Cookie installing Net::HTTP::UserAgent installing Net::HTTP::UserAgent::Robot ... Okay, so maybe we all decide that HTTP is such an important protocol that it should be pushed up as HTTP::*, or maybe even, oh, I dunno, LWP::* (that makes sense to everyone, right? ;) Mark my words: any "convenient" flattening will come back to haunt us later in the game, as I think the Perl 5 CPAN experience has taught us to some degree (witness IO::*). No one wants to type a million "::"s, but at some point the community has to decide: are we making a bunch of neat/useful modules as a hobby, or are we actually trying to build a standardized, logical, robust, self-consistent framework of code that spans the entire range of possible applications? --- I think that's it for now...more to come, I'm sure :) -John
Re: Perl 6 modules plan
On 8/24/01 11:52 PM, John Siracusa wrote: > I mentioned this on another list, and I thought I'd bring it up here as > well. I think NeXT-style "bundles" offer an interesting solution for > keeping several versions of a single library installed at the same time, > with well-defined major/minor version compatibility rules. This > functionality becomes even more important with the proposed ability to > specify modules by version (or version range, etc.) More information on > bundles is available at Apple's web site. I think there are some ideas > worth stealing here: > > http://gemma.apple.com/techpubs/macosx/Essentials/SystemOverview/Bundles/ Actually, going directly to the section on Frameworks (bundles that encapsulate libraries, as opposed to applications or plug-ins) is probably more useful: http://gemma.apple.com/techpubs/macosx/Essentials/SystemOverview/Frameworks/ -John
