in reply to Method parameters validation and inheritance

In referen to naming conventions, I have a simple rule, make it simple to read, it will be simple to program. This basically means,

  1. Avoid abbreviating. This is not the 'Wheel of Fortune' you can spell out whole words.
  2. Avoid writing sentences. You should be able to name a method to encapsulate its utility in no more than 3 words. Anything more it start to sound like a government agency.
  3. Name your method within the context it is being used. You know what subject you are talking about, don't be verbose about it.

Taking the example of some of your code above, 

my $context = $file->open_for_reading( {} );

## Change to
#############################
my $context = $file->reading;

[download]
my $context_derived
    = $file_derived->open_for_reading( { 'path' => $file, 'join_longca
+lls' => 1 } );

[download]

What the hell is 'join_longcalls'? For some reason it sounds like a pirate, and it is basically incomprehensible so it might was well be a pirate. Make it read like you actually write, don't make something up and hope people understand what the hell you are talking about.

Replies are listed 'Best First'.
Re^2: Method parameters validation and inheritance
by TGI (Parson) on Sep 19, 2008 at 07:09 UTC

    This must that "pirate software" I keep hearing about!

    Really, there's no reason to stop there! 

    use Acme::Lingua::Pirate::Perl;

...

my $context_derived = $file_derived->open_for_reading( { 
    'path' => $file, 
    'join_longcalls' => 1 
} );

scuttle her matey "Avast! Context error - " $file_derived->error
    if $context_derived be '' curse ye deadlights;

    [download]

    Of course, roman may prefer other dialects.

    Time for a brief lapse into serious commentary, and nitpicking. The problem I see with "join_longcalls" is that isn't "join_long_calls". Consistent formatting of parameter names, variables and function/method names is important. Otherwise you wind up with PHP.


    TGI says moo

[reply]
[d/l]

      Thanks for your comments. I should probably give some longcalls explanation.

      Code sample given is a simplified but real world example: $file encapsulates a binary file (log) produced by a phone switch. It contains cdrs (Call Data Records) describing voice calls carried out. The file is used as a source for several target applications (billing, dwh).

      If a call continues longer than say half an hour it is logged by parts. If join_longcalls is set for open_for_reading only complete calls are produced by read_cdr and the total duration of the call is summed up.

      So the join_longcalls flag really causes the long calls to be joined. In such case I am not sure whether to use join_long_calls or joins_long_calls?

      I think open_for_reading is clearer than plain reading since I try to use imperative for my subs.

      As kyle suggested, I could avoid some of the "SUPERs" and turns the code into:

      my $context = $file->open_for_reading({'path' => $path});
$context->joins_long_calls(1); 
# or better like this, 
# because there is no property join_long_calls
$context->join_long_calls;

      [download]

      The open_for_reading, actually returns Class::Prototyped based object, so join_longcalls - whatever its implementation is - actually wraps read_cdr method.

      This approach has some advantages:

      • The interface of open_for_reading remains same across classes.
      • It is more self checking - since the parameters were turned into method calls, which fail when called but not defined.

      This approach has also some disadvatages:

      • Although $lc->join_long_calls can be called anytime, it make sense only immediately after open.
      • When I have target file (representation of the billing, dwh file) I could have previously used a declaratory source_params method containing the parameters to be passed to open_for_reading, now I had to redefine some open_source method.
[reply]
[d/l]

In Section Seekers of Perl Wisdom