in reply to Re: Perl Programming guidlines/rules
in thread Perl Programming guidelines/rules

If you find yourself commenting your variable names then you probably didn't spend enough time thinking of a good name for it.

Remember too that there's a difference between parameter names and variable names. In a dynamic language, a parameter name should probably suggest its type, variables should suggest their role. Kent Beck is really good on this in 'Smalltalk Best Practice Patterns'.

  • Comment on Re: Re: Perl Programming guidlines/rules

Replies are listed 'Best First'.
Re: Re: Re: Perl Programming guidlines/rules
by mirod (Canon) on Nov 22, 2002 at 13:49 UTC

    Simple scalars may often have descriptive names, but I just wrote this:

    my $standard={}; # the structure that contains all the standard info # a hasref to # title => "standard title" # dir => standard directory (where the standard +page and graphics are) # des => designation (802.11a-2000) # norm_des => normalized designation (802_11_a_2000) # def => hasref { term => "html definition" }

    I found this kind of comment to be immensely useful several month later when I need to fix a bug (rare ;--) or to add features to the code (often!).

    And yes, the data represents a view of a standard, hence its name, but there are many infos that can be stored about a standard, it helps to know exactly which one this data structure is providing.

    BTW, while I agree that this structure could be an object, I don't think that the specific program I am working on requires OO. And in any case it is nice to have all the docs about the variable right where I declare it.

      Oh, I'd definitely make that an object. If only so I could either make normalized_designation a computed attributed, or at least write a set_normalized_designation that looked something like:
      sub set_normalized_designation { my $self = shift; my $designation = shift; $self->ensure_normalization($designation); $self->{normalized_designation} = shift; } sub ensure_normalization { my $self = shift; my $designation = shift; $designation =~ /.../ or die "$designation is not correctly normalized"; }
      You could certainly argue that this might be considered long winded, but writing things this way makes assumptions explicit and ensure that they're enforced.

      Of course, in Perl 6 you can have your cake and eat it:

      class Thing { my $.title is rw; my $.standard_directory is rw; # Where graphics etc are found my $.designation is rw; my Hash $.def; # Use another class? method normalized_designation { my $normalized_des = $.designation; $normalized_des =~ s/.../.../; return $normalized_des; } }
      Now, I might be a little behind on Perl 6 OO, but ISTR that setting is rw on object attributes will autogenerate accessors. If not I'm sure someone will subclass Object to do the right thing.

      Note that, in not much more space than it took to comment your hash you have an object, and, for free you get a restricted set of keys, and your dependent field removed and replaced with a computation, and you've got somewhere to hang common behaviour relating to this data structure.

      Damn, but I want Perl 6 soon.

        The only reason the normalized designation is a field is purely a syntactic one: it makes it (admittedly slightly!) easier to print within a string: print qq{$standart->{des} ($standart->{norm_des})\n}; looks nicer than print qq{$standart->{des} (} . normalized( $standart->{des}) . qq{)\n};. Otherwise it would be really easy to use a Memoize-ed function to compute it on the fly.

        And (before you jump on this one ;--) yes, if I used objects I could use the printf version which looks ok: printf( "%s (%s)\n", $standard->des, $standard->norm_des);

        I guess it's purely a matter of personal preference here, but I usually leave OO out of smallish scripts, and comment my data structures.