Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

when to capitalize package variables

by Lotus1 (Vicar)
on Feb 06, 2021 at 01:57 UTC ( #11127962=perlquestion: print w/replies, xml ) Need Help??

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

I need to provide a package variable in a module I'm working on to let the user turn on or off a feature. It's a simple non object oriented module. I've used Data::GUID::Any before and remembered there is a package variable called UC that is used exactly like what I want to do. The user can get lower case GUIDs by setting it to false but it defaults to positive.

local $Data::GUID::Any::UC; guid_as_string(); # will be lower case

My question is since this variable isn't a constant should it be uppercase? Perhaps the author just wanted to avoid having it look similar to uc().

Replies are listed 'Best First'.
Re: when to capitalize package variables
by kcott (Bishop) on Feb 06, 2021 at 08:45 UTC

    G'day Lotus1,

    You could follow the convention used by Data::Dumper. It has a couple of screenfuls of "Configuration Variables":

    $Data::Dumper::Indent $Data::Dumper::Trailingcomma $Data::Dumper::Purity ... lots more ... $Data::Dumper::Sortkeys $Data::Dumper::Deparse $Data::Dumper::Sparseseen

    So that would suggest: $Data::GUID::Any::Uppercase.

    That, however, is counter-intuitive. If the purpose is to choose lowercase, $Data::GUID::Any::Lowercase would, in my opinion, make a lot more sense. Default would be FALSE; set it to TRUE if you want lowercase.

    I see you've already received conflicting advice; you may get more. There's really no convention for this; for instance, I've frequently seen $DEBUG. Perhaps the best advice is to make your own choice then use it consistently across your modules. Just to expand on the Data::Dumper example, I know I'd find it very annoying if I had to continually check the documentation to see whether I needed useQQ or useQq or UseQq or ... you get the picture: they all have the same format; in this case, Useqq.

    — Ken

      That, however, is counter-intuitive. If the purpose is to choose lowercase, $Data::GUID::Any::Lowercase would, in my opinion, make a lot more sense. Default would be FALSE; set it to TRUE if you want lowercase.

      Good point. But I think the reason for that choice was to let the user do local $Data::GUID::Any::UC; to change the value to false. I'm doing my package variable the way you propose where I set it to '1' or do a ++ to activate it. The special variable $| works that way but that is something different. I digress.

      My variable is called $Data::QuickMemoPlus::Reader::suppress_header but I'm thinking I'll redo that now after all the good comments I've received.

Re: when to capitalize package variables
by haukex (Bishop) on Feb 06, 2021 at 08:48 UTC

    Just to throw another opinion into the mix: Sometimes one sees such variables strictly titlecased, since they're package variables but not constants, like for example the options in Data::Dumper (e.g. $Data::Dumper::Sparseseen or $Data::Dumper::Maxdepth). So for example $Data::GUID::Any::Uc may not seem to make as much sense as uc or UC, but it indicates it's a package variable since it's titlecased, but not a constant since it's not all uppercase. (I see kcott posted the same point as I was writing this)

    The casing of variable names is just a convention and not a strict rule. Anyway, if you want my opinion on the following:

    I need to provide a package variable in a module I'm working on to let the user turn on or off a feature. It's a simple non object oriented module. I've used Data::GUID::Any before and remembered there is a package variable called UC that is used exactly like what I want to do.

    I would suggest not using a package variable at all. Despite the longer names, they're not really different from other globals like $/, and come with all the same potential issues: One has to remember to use local, and even then, dynamic scope might bite you lower down in the call stack. If you don't want an OO interface, then give your functional interface parameters to configure options.

    use warnings; use strict; { package Foo; our $DEFAULT_BAR = 1; sub foo { my %opts = @_; $opts{bar} //= $DEFAULT_BAR; print "bar=$opts{bar}\n"; } } Foo::foo(); # prints "bar=1" Foo::foo(bar=>2); # prints "bar=2"

    I usually set up package variables like $DEFAULT_BAR such that I can easily change the defaults, this can also be useful for testing, but I also usually leave them undocumented since I don't want to encourage the use of these globals. Also the above code could of course do some validation on foo's @_, but I omitted that for brevity.

      I would suggest not using a package variable at all
      Agreed. I see in On Interfaces and APIs that Conway's SAT talks propose some sound general interface advice namely:
      Make common usage the default; allow uncommon usage via optional attributes
      ... with hashes being the natural way to implement that in Perl.

      In your Foo::foo(bar=>2) example, I note you used a hash rather than a hash ref. I've always used a hash ref, as recommended in PBP ... though, as indicated here, that was an error (compile-time vs run-time boo-boo) in the book from TheDamian - though he still stands by the advice.

      As a Perl beginner, I chose a simple non-OO interface in the Acme::EyeDrops sightly function way back in 2001, four years before PBP was published. I remember liking that interface at the time because it allowed me to add new attributes in the future without breaking old programs. Plus I've always hated global variables (in any language) and couldn't bring myself to create a public global variable in my first Perl module. :)

Re: when to capitalize package variables
by stevieb (Canon) on Feb 06, 2021 at 02:17 UTC
    "My question is since this variable isn't a constant should it be uppercase?

    Personally for me, never. I only upper-case constants, and I upper-case the entire thing.

Re: when to capitalize package variables
by AnomalousMonk (Bishop) on Feb 06, 2021 at 02:36 UTC
    It's a simple non object oriented module.

    I would tend to lower-case this variable as stevieb would, but for me the more important consideration is use of the fully-qualified format $Data::GUID::Any::UC (or $Data::GUID::Any::uc) for a variable of this type which is intentionally not exported from its module; this format makes it quite clear what's going on IMHO, i.e., use of a package-global. Lc-first camel-casing is also an option for compound names: $Data::GUID::Any::upperCase.


    Give a man a fish:  <%-{-{-{-<

Re: when to capitalize package variables
by jcb (Parson) on Feb 06, 2021 at 02:23 UTC

    In this case, since the name is itself a quasi-acronym, all-uppercase is fine.

    I normally use all_lowercase for local variables, CapitalizedCamelCase for global variables, and ALL_UPPERCASE for constants, but very short names can end up all uppercase as well, if that seems to make sense in context. In your case, since you are "following suit" with a feature of another package, I say that "UC" makes sense in context.

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (5)
As of 2021-10-15 20:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My first memorable Perl project was:







    Results (68 votes). Check out past polls.

    Notices?