A question of Style, was: SPUG: Sort an array question

Terry Nightingale tnight at pobox.com
Fri Dec 27 13:46:40 CST 2002


I'm usually not very vocal on SPUG, but since the topic has turned to 
coding style, I'll chime in with my $0.02:

Seeing as how Larry Wall is both a brilliant engineer and a linguist, 
the "There's More Than One Way To Do It" aspect of Perl is, in my 
opinion, no accident.  Because of TMTOWTDI, we can act like writers or 
speakers, and choose the most appropriate way to do it for our intended 
audience.

When writing a short one-off system administration script, for example, 
feel free to use one-character variable names and obscure idioms in the 
name of getting something done as quickly as possible.  Just be sure you 
recognize when code is truly "one-off", and not the foundation of a 
larger system.

Much more often, your audience is "the maintenance programmer who 
inherits this code."  When writing to this audience, optimize for 
readability. Use descriptive (but not verbose) variable names, and 
comment the intent (not the mechanics) of your code.  Comments are most 
valuable when they capture the relevant information from the "sitting 
and thinking" process that Peter describes.  Comments should be clear, 
concise, and to the point.

When writing code intended to be maintainable, try to keep these 
questions in the back of your mind:

What would a maintainer understand most quickly and most easily? 
Another way to say it:  How can I save time and frustration on the part 
of the maintainer?  For example, you might choose a simpler, more 
obvious way of doing something over the elegant and perhaps more obscure 
method that's "cool" or demonstrates your programming prowess.

Where in my code would a maintainer not understand why I wrote it this 
way?  Comment these sections, telling why the chosen approach was 
chosen.  Was it done for better performance?  Was there a data security 
concern?  Did you copy the code from the Foo::Bar module on CPAN because 
it just plain worked and saved you the time of reimplementing the same 
algorithm?  Knowing such things really helps as a maintenance programmer.

Well, I think that's at least two cents worth.  Happy Holidays, everyone.


Peter Darley wrote:
> William,
> 	Since you address style in your message, let me say that I agree with
> everything you said, but by my way of thinking, have left something out.
> 	In my opinion one of the biggest things that promotes readability is the
> use of long variable names.  Since when I program I spend far more time
> sitting and thinking about how I want the program to work than I do actually
> typing things in, using short variable names ($i, etc.) seems like
> optimizing for speed of typing over ease of programming (readability).  That
> seems a bit backward to me.
> 	When digging through other peoples code to figure out what I'm doing wrong
> when calling it, there's nothing more frustrating that running across
> something like the following lines (from Apache::DBI):
> 
> my($r, $q) = @_;
> my(@s) = qw(<TABLE><TR><TD>Datasource</TD><TD>Username</TD></TR>);
> 
> 	What's $r or $q?  What is the @s array for?  How can I call this thing
> correctly if I don't know what variables to pass it?  I can figure out what
> they are, but wouldn't it be better to use a longer, more descriptive
> variable name?  This problem gets significantly worse in the traditionally
> poorly documented internal tools that are often maintained by someone who
> didn't write them.  When trying to debug old code the last thing you want to
> see is a line like.
> 
> $i=$Namespace::h || $Namspace::n unless $o;
> 
> 	Just my 2 cents.
> Thanks,
> Peter Darley
> 
> -----Original Message-----
> From: owner-spug-list at pm.org [mailto:owner-spug-list at pm.org]On Behalf Of
> William Julien
> Sent: Thursday, December 26, 2002 5:46 PM
> To: blueovalfun at yahoo.com; spug-list at pm.org
> Subject: Re: SPUG: Sort an array question
> 
> Although basic, this is actually a very interesting problem. There is
> more than one way to sort an array. Consider, for example a mixed array
> of numbers and characters. The standard perl sort puts a "12" before a
> "2". Mixed alpha and numeric elements require special handling. What is
> "correct", depends on the expectation of the user (programmer).
> 
> I wish you luck in finding new opportunities. To help, I offer a few humble
> suggestions and sample code. These are issues of style, religion, and art;
> not science.
> 
>     White space is "good". It enhances the readability of the code.
> 
>     Divide your code into logical segments. The code below starts with a
>     comment block with provides "who, what, when, where".  This is good
>     in a corporation when the reader needs to "kill the author". :-)
>     What follows are a module, variable and initialization sections.
>     Each major functional unit has a comment.
> 
>     I comment sections for "what is does", not "how I do it". If
>     particular lines require explaination, I place them on the right
>     of the line. I never comment control structures ("end for while").
>     If the person reading the code can't figure that out, they need to
>     get a job in the service industry.
> 
>     I use the "my" scoping block to document the purpose and use of
>     each variable. Again, this is just my style. There is no wrong way.
> 
>     Finally, think about ways to simplify and reduce the number of
> variables.
>     The line "foreach (@array1) {$arrayCnt++;}"  is not necessary since
>     "$#array1;" provides the same answer (but zero based). General rule of
>     thumb: When you find your "my" block filling with control variables,
>     it's time to think if a better way. This is really important when the
>     program starts getting large.
> 
> William Julien
> (vi bill)
> 
> Sample run:
> 
> -->bubble.pl
> Original array: e 42 c g h z Man 2 t a 5 i 6 Cat j l 33 12 p b r q x v a
> Perl Sort:      12 2 33 42 5 6 Cat Man a a b c e g h i j l p q r t v x z
> alt Perl sort:  2 5 6 12 33 42 Cat Man a a b c e g h i j l p q r t v x z
> Bubble sorted:  2 5 6 12 33 42 Cat Man a a b c e g h i j l p q r t v x z
> 
> Here is the code:
> 
> #!/usr/bin/perl -w
> #
> # Spug sort example
> #
> # William Julien
> # catmanor.com
> # 12/26/2002
> ###
> 
> #
> # modules
> #
> use strict;
> 
> #
> # variable declarations
> #
> my (@array,	# an unsorted array
>     @sorted,	# a sorted array
>     $i,		# loop index
>     $j,		# loop index
>     $tmp,	# a temporary place
>     );
> 
> #
> # initialization
> #
> @array = qw(e 42 c g h z Man 2 t a 5 i 6 Cat j l 33 12 p b r q x v a);
> 
> #
> # print original, perl sort, and alpha/numeric sort
> #
> print "Original array:\t at array\n";
> @sorted = sort @array;
> print "Perl Sort:\t at sorted\n";
> @sorted = sort { $tmp = $a . $b;
> 		 ( $tmp =~ /\D+/ ) ?  $a cmp $b : $a <=> $b
> 	       } @array ;
> print "alt Perl sort:\t at sorted\n";
> 
> #
> # sort array using a bubble sort
> #
> for( $i = 0; $i <= $#array; $i++ ) {
>     for( $j = $i+1; $j <= $#array; $j++ ) {
> 	$tmp = $array[$j] . $array[$i];		# join compare elements
> 	if ( ( $tmp =~ /\D+/ ) ?		# use alpha if not numeric
> 		$array[$j] lt $array[$i] :	# alpha
> 	    	$array[$j] < $array[$i]  	# numeric
> 	   ) {
> 		$tmp = $array[$j];		# save element
> 		$array[$j] = $array[$i];	# swap
> 		$array[$i] = $tmp;		# restore element
> 	   }
>     }
> }
> 
> #
> # print bubble sorted array
> #
> print "Bubble sorted:\t at array\n";
> 
> #
> # fin
> ###
> 
>  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
>      POST TO: spug-list at pm.org       PROBLEMS: owner-spug-list at pm.org
>       Subscriptions; Email to majordomo at pm.org:  ACTION  LIST  EMAIL
>   Replace ACTION by subscribe or unsubscribe, EMAIL by your Email-address
>  For daily traffic, use spug-list for LIST ;  for weekly, spug-list-digest
>      Seattle Perl Users Group (SPUG) Home Page: http://seattleperl.org
> 
> 
>  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
>      POST TO: spug-list at pm.org       PROBLEMS: owner-spug-list at pm.org
>       Subscriptions; Email to majordomo at pm.org:  ACTION  LIST  EMAIL
>   Replace ACTION by subscribe or unsubscribe, EMAIL by your Email-address
>  For daily traffic, use spug-list for LIST ;  for weekly, spug-list-digest
>      Seattle Perl Users Group (SPUG) Home Page: http://seattleperl.org
> 
> 

-- 
Terry Nightingale <tnight at pobox.com>
Web Developer, Philosopher, Geek
"In theory, there is no difference between theory and practice. But, in
practice, there is." -- Jan L.A. van de Snepscheut


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     POST TO: spug-list at pm.org       PROBLEMS: owner-spug-list at pm.org
      Subscriptions; Email to majordomo at pm.org:  ACTION  LIST  EMAIL
  Replace ACTION by subscribe or unsubscribe, EMAIL by your Email-address
 For daily traffic, use spug-list for LIST ;  for weekly, spug-list-digest
     Seattle Perl Users Group (SPUG) Home Page: http://seattleperl.org




More information about the spug-list mailing list