Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Perl Naming Conventions

by Anonymous Monk
on Apr 28, 2003 at 19:11 UTC ( [id://253796]=perlquestion: print w/replies, xml ) Need Help??

Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

Hi!

I'm in the middle of learning OO Perl. I'm wondering if there exist any conventions about naming methods, attributes, instance variables etc. My question isn't OO Perl specific and could also be extended to functional Perl.

Given a subroutine/method to get a value I saw the following versions:

getValue { ... }
get_value { ... }
getvalue { ... }

Also with named attribute there are different versions:

my $foo = new foo( AttributeName => "name", attribute_name => "name", attributename => "name", );

The same applies to variable names, package/class names, etc.

Are there any specific suggetions, guidelines or conventions for this?

Thanks, Kurt

Replies are listed 'Best First'.
Re: Perl Naming Conventions
by TVSET (Chaplain) on Apr 28, 2003 at 19:50 UTC
    While there are things like perlstyle and numerous coding style guides on the web, it is still a matter of personal prefrence.

    I myself got used (or still trying) to the following:

    • Objects and modules names start with capital letter (eg: My::Module).

    • Methods use underscore character ("_") as a word separator and start with the word, which describes the actrion (eg: get_value(), set_value(), print_report()).

    • Something, I've learned from PHP - start methods/subs names which return TRUE/FALSE with "is" (eg: is_valid_type(), is_valid_age(), is_logged_in()). These makes code way more readable.

    • If sub/method needs only one argument, don't use arrays, hashes, or references. Just call the damn thing! (eg:is_valid_type($type))

    • If sub/method needs more then one argument, for maintainers sake, use named arguments in hash or hash reference. (eg: print_report({-colored=>1, -monthly=>0}))

    • When it comes to parameter names, I like CGI.pm's style - with the dash. (eg {-colored=>1, -monthly=>0}).

    • I like to keep inline documentation with POD and perl comments. All irrelevant staff, like AUTHOR, NOTES, BUGS, etc (grin) I usually move to the bottom of the module file.

    • Document with POD only methods which can be called from outside. The rest should be documented with perl comments in the source. Otherwise - with POD, but should be marked explicetly.

    One other thing I want to add is that coding style is not something that you think about, develop, and then use forever. It changes slowly, but constantly with the experience. Especially, if that experience is with someone else's code. :)

    P.S.: In general, I don't like capitalization, since it requires me to press more keys then I need to. So I use it ONLY for significant names, which are obviously ONLY the modules. :)

    P.P.S: And, yes, I beleive that set_value() is easier to read then setValue()

    Leonid Mamtchenkov

      a thing I like to do is put a leading underscore on methods that should not be called directly e.g.
      ... sub external { ... _internal(); ... } sub _internal { }

      this is just a hint to the class user, of course. I also do the same for function-style modules, I put required methods in EXPORT, internal functions in EXPORT_OK, and provide :std and :test tags in EXPORT_TAGS that are EXPORT and EXPORT_OK e.g.
      @EXPORT = qw(external interface); @EXPORT_OK = qw(_internal _interface); %EXPORT_TAGS = (STD => \@EXPORT, TEST => \@EXPORT_OK);
Re: Perl Naming Conventions
by halley (Prior) on Apr 28, 2003 at 19:15 UTC
    See (perldoc perlstyle): perlstyle.

    For object attribute accessor methods like this, I prefer this idiom:

      sub value { my $self = shift; return $self->{value} if not @_; $self->{value} = shift; }

    Thus, you can say $x = $o->value, or $o->value(5);.

    --
    [ e d @ h a l l e y . c c ]

      Thanks for the link. Unfortunately the text describes only the basics.

      I often OO modules on the CPAN which have the following style:

      Methods:

      get_value { ... }; set_value { ... };

      Attributes:

      my $foo = new foo( PrintError => 0, RaiseError => 1, );

      One example is DBI.

      Now I'm wondering if this is a convention or just because the author of the module likes it.

        If more than two modules do it, it's a convention. In all matters of style, "consistency isn't."

        That said, the convention of passing named pairs is pretty commonly used. Whether the names are capitalized or punctuated varies. Whether the pairs are stored as attributes, or invoke special features, varies. It's enough of a convention that I hear that perl6 will offer a couple new features for parameter-checking these named arguments.

        I'd say the get_ and set_ naming idea is more of a porting convention to be similar to languages that can't overload their methods. The style I proposed above wouldn't work in languages or libraries which couldn't distinguish the calling context or treat the arguments differently.

        --
        [ e d @ h a l l e y . c c ]

      I also prefer this idiom. It was only an example to make clear what I mean with "different method names" :).

Re: Perl Naming Conventions
by John M. Dlugosz (Monsignor) on Apr 28, 2003 at 21:53 UTC
    A number of years ago I looked into which is more readable, this_name or ThisName. The descriptions people had about their perceptions indicate that the font has a lot to do with why this_name is unreadable to some. That is, the underbar is too faint or too low. In testing comprehension and reaction times, ThisName is the worst in this meaning of readability.

    In terms of maintainability, simply having a convention is the important part. Comprehension and memory of the human reader is largely case-insensitive and delimiter-insensitive. Larry might argue that the programming language should match our perceptions on this issue. Hey, it worked for Pascal.

Re: Perl Naming Conventions
by TomDLux (Vicar) on Apr 29, 2003 at 13:46 UTC

    Daniel R. Allen did a presentation on Style Guides to the Toronto Perl Mongers last week, and since I had been meaning for a while to research the topic, I gathered together links to relevant information. Dan's research for his talk included this Perlmonks discussion thread

    While I have preferred capitalizing words, the documents I found convinced me to change to using underscores. The spacing makes it easier to see where one word ends and another begins. While the underscores make the word longer, that discourages excessively verbose variable names.

Re: Perl Naming Conventions
by Anonymous Monk on Apr 28, 2003 at 19:53 UTC

    As I'm not sure if I my question is comprehensible (excuse me, English is not my mother tongue) here's what I'm looking for in a nutshell:

    Code Conventions (especially naming conventions) for Perl, like the ones for Java (especially Chapter 9).

      There isn't an official style document but perlstyle offers some advice on naming conventions, and there are some other conventions:
      • Module names are MixedCaseNoUnderscores
      • Constants are UPPERCASE_WITH_UNDERSCORES
      • Package wide variables are Mixed_Case_With_Underscores
      • Function variables are lowercase_with_underscores
      Also, function and method names are also lowercase_with_underscore

      This isn't complete or in any way authoritive, but in my opinion it's a good start. Take a look at the modules which are in the Perl distribution. They mostly follow the conventions listed above.

      TVSET makes some good comments about the readability of your code.

      If your code is readable, and you're consistent in whatever naming convention you use, you'll have maintainable code. If you're planning on putting modules on CPAN, then examine some of the more well-known modules (like DBI and LWP) to see what the naming conventions are.

      Arjen

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://253796]
Approved by Paladin
Front-paged by Coplan
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others goofing around in the Monastery: (6)
As of 2024-03-19 11:28 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found