Re: Improve readability of Perl code. Naming reference variables.

[stevieb]

This is one of the many benefits of keeping your code blocks (scope) as small as possible (one screen if possible), as it allows you to visually see what you're dealing with in regards to a variable.

To further, variable naming is important, as is attempting to write your subroutines so they only do one thing, as opposed to a whole bunch of things. This:

my $var->@;

... is far too much typing just for visual purposes (imho), and it adds unnecessary noise. It's just as easy to scope properly and name things appropriately:

my $cat;

That's singular, so I'd put money on the fact it's a scalar (unless it's an object, but if it's an object, it'll be being used much differently than a simple scalar so I digress).

my $cats;

# or

my $cat_list;

...or:

my $cat_map;

Both of those are extremely easy to identify to even a low-intermediate Perl hacker as an array reference in the former case, and a hash ref in the latter (perhaps the author has a hash of cat names to cat colours ;).

What's more, if there is confusion, in decently laid out code, one may have to scroll up only a tiny bit (if at all) to see where the variable is being declared/defined. If you have to search all over the code for where variables are defined, the scope for that variable is not small enough.

Even if you get the type wrong, with use strict; and use warnings; will always let you know the what/where of the problem.

So, in essence, I understand what you're desiring here, but good coding practices alleviate us from (for the most part) needing such visual cues.

[hakonhagland]

Yeah. I completely agree with you with the idea of keeping subroutines or code blocks small. It is also my experience that this coding style (that you propose) has potential for eliminating most readability issues. So the naming issue can usually be circumvented using proper naming of variables and keeping the scope small. But it's also my experience that in some cases it would still be beneficial to have the option to further document the type of a reference variable.

[stevieb]

What you're referring to in your last sentence is what some call "edge cases". These edge cases, where there may be ambiguity to the reader of the code is where your extremely brief comments should go. Code should document itself, but if you feel the reader may scratch their head:

...

my $x = thing_list(); # href
...

Of course, that's a pretty trivial example, but you get the point.

[hakonhagland]

Hi stevieb,

Yes I think I get the point :) But consider another example, a sub routine is called with three references. A scalar reference, a hash refernece, and an array reference. Here is an example of a corresponding sub definition:

sub func {
   my ( $str, $desktop_info, $files ) = @_; #sref, href, aref

  ...

}

In this case your end-of-line comment could work. But would it not be better if the comment could be avoided? If the variable names were self-documenting there would be no need for the comment. And the code should be easier to maintain. If you change the arguments to func you do not need to also remember to update the comment:

sub func {
   my ( $str->$, $desktop_info->%, $files->@ ) = @_; 

  ...

}