Tuesday, March 10, 2009

Perl naming convention for subroutine names

Disclaimer
Welcome to all readers of Perlsphere. Mine is a blog of little pretention where I narrate my personal experience with learning Perl. As such, the code that can be found in DamienLearnsPerl's pages should be taken with a grain of salt as it might be inaccurate (oops). I am calling upon the understanding and experience of more proficient Perl users to point out those mistakes or suggest better and more "perlish" ways to program.

Perl Naming Conventions
For example, my last post about the twitter script triggered an interesting comment today.
Anonymous said...

Some new Perl culture for you to learn: subroutine names that are AllSquishedTogether() are frowned upon. The convention is names_like_this() - lowercase, with underscores separating words.

My first reaction was: "As long as I am using a way to name variables and methods that is coherent throughout the program, why couldn't I CapitalizeAndSquish as I please?"
Then I got to think: "Well, I guess that would be alright if I was the only person maintaining the script. But what would happen on projects where several developers contribute to the code? There would need to exist a common naming convention, so that the code doesn't look like a patchwork of different tabulation and personal formatting standards..."

So, tickled by Anonymous' remark, I embarked upon a Google trip to uncover documented Perl naming conventions...

The first tip I found was from webreference.com:
When selecting names for your general subroutines, it's recommended that you use all lower case names; since, by convention, subroutine names with all capital letters indicate actions that are triggered automatically as needed by Perl; such as AUTOLOAD or DESTROY, and mixed case names are often utilized as package names. [...] keep your user-defined subroutine names to all lower case and you'll avoid this ambiguity in the future.
There is more or less the same description from perldoc perlsub:
Subroutines whose names are in all upper case are reserved to the Perl core, as are modules whose names are in all lower case. A subroutine in all capitals is a loosely-held convention meaning it will be called indirectly by the run-time system itself, usually due to a triggered event. Subroutines that do special, pre-defined things include "AUTOLOAD", "CLONE", "DESTROY" plus all functions mentioned in perltie and PerlIO::via.
The Camel book also adds that all upper case subs could be used for constants.

However, I also found this tutorials:
- Picking Up Perl (granted, it's from 2001), where they show an example of a subroutine called HowdyEveryone{}

I continued my journey and stumbled upon the Perl::Critic::Policy::NamingConventions::Capitalization and Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseSubs modules on CPAN. They are both based upon recommendations from Damian Conway's book Perl Best Practices and enforce the all-lower-case-naming policy for subroutines.

But the piece of information I found most useful was definitely perlstyle, the Perl style guide. There can be found a list of recommendations to make your Perl program easier to maintain and understand. Abstract:
  • While short identifiers like $gotit are probably ok, use underscores to separate words in longer identifiers. It is generally easier to read $var_names_like_this than $VarNamesLikeThis, especially for non-native speakers of English. It's also a simple rule that works consistently with VAR_NAMES_LIKE_THIS.
  • Function and method names seem to work best as all lowercase. E.g., $obj->as_string().

    You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it.

I will therefore try to follow the following guidelines:
- ALL CAPS: automatically triggered subroutines and constants
- Mixed Case: package names
- lower case with words separated by underscores: variables and user-defined subroutines
- lower case starting with a "_": internal function/variable

What about you? What do you take as reference for naming conventions? Do you use different standards than those described in perltype?


3 comments :

  1. That's a really helpful article. I was just getting caught up trying to work out what conventions I should use myself and came across your post and it seems nice and logical to me!

    ReplyDelete
  2. You are fascinating. I like that your first response to Anonymous's criticism was to want to defend your own naming convention, but your common sense drove you to look for reasoning behind the comment. I like that you researched his/her reasoning and found the logic in what you should be doing. Bravo.

    ReplyDelete
  3. For what it's worth, the author of Picking Up Perl has disclaimed his book as out of date, so I'd not recommend using it as a reference guide: \

    http://identi.ca/conversation/67788988#notice-68638672

    ReplyDelete