Path: utzoo!attcan!uunet!jarthur!usc!apple!rutgers!bellcore!decvax!bar!dcj
From: dcj@bar.ZK3.DEC.COM (Dave Jedlinsky OSEM)
Newsgroups: comp.lang.postscript
Subject: Re: indentation style
Message-ID: <6566@decvax.dec.com>
Date: 7 Feb 90 18:44:22 GMT
References: <17880@rpp386.cactus.org> <17807@rpp386.cactus.org> <9002040147.AA16999@en.ecn.purdue.edu> <45829@wlbr.IMSD.CONTEL.COM>
Sender: news@decvax.dec.com
Reply-To: dcj@bar.ZK3.DEC.COM (Dave Jedlinsky OSEM)
Organization: Ultrix Engineering Group
Lines: 154

# Eat this, line eater!

In article <17880@rpp386.cactus.org>, woody@rpp386.cactus.org (Woodrow
Baker) writes:
> Concerning programming styles:
>  
> Glenn, don't take this personally, but....
> A particularly odious example is found on page 74 of the GREEN book.
>  
> AS WRITTEN:
>  
> /SH {%def
>         dup stringwidth pop
>         currentpoint 3 1 roll
>         add 300 gt { %if
>             72 exch 48 sub dup 36 lt { %if
>                showpage
>                pop 700
>             }if
>             moveto
>         }{ %else
>             pop
>         }ifelse
>         show
> }bind def        
>
> This code suffers from the following problems:
>
> [ 6 valid complaints deleted to save vertical space ]
>
> It should be re-written like this:
>  
> %
> % comments about the function, it's parameters, and what it does.
> %
>  
> /SH 
>         {        
>         dup stringwidth pop
>         currentpoint 3 1 roll add 
>         300 gt                          % related operations
>                 { 
>                  72 exch 48 sub         % related operations
>                  dup 36 lt                 % related operations
>                         { 
>                          showpage
>                          pop 700        % related operations
>                         }if
>                  moveto
>                     }
>                 { 
>                  pop
>                 }ifelse
>         show
>         }bind def
>         

In general, I agree with Woody's complaints about Glenn's preferred
style.  However, in an earlier message, Glenn also proposed an alternate
style which I believe meets your criteria for readability, and I find is
easier to read than the sample immediately above.  Using the same
procedure above, here is my preferred style:

/SH % (string) SH -	<- I think that is correct, but the idea is there.
{
	dup stringwidth pop
	currentpoint 3 1 roll
	add 300 gt			% related operations
	{
		72 exch 48 sub		% related operations
		dup 36 lt		% related operations
		{			
			showpage
			pop 700		% related operations
		} if
		moveto
	}
	{
		pop
	} ifelse
	show
} bind def

Following your guidlines, these are the advantages of this style:

> 1. You can instantly find any pair of curly braces.  Just scan down
>    the column under the brace.

> 2. The procedure name is clearly set off by it's self.  It can
>    be found easily in a larger program.

> 3. The controlling test for the if and ifelse can be instantly found.

> 4. Comments line up neatly in the same vertical column on the right.

> 5. Related operators are grouped together.

> 6. It passes the 15 second rule.

In addition:

7. You know what to put on the stack for the procedure, and what is
   there afterwards.  Just look for the procedure name.

8. It makes more sense regarding nesting levels (which Glenn mentioned
   in the article where he proposed this alternate style).  The curly
   braces cause the level to go one lower, but they themselves are on
   the higher level. (Does that make any sense?)

9. I like the way it looks. :-)

> While these are "style" issues, they have a much deeper impact.  One should
> program, not for oneself, but with the poor bugger who will follow you
> in mind.  Software Engineers rarely stay in one place long.  You not
> only wind up costing the company money after you are gone, but you also
> wind up causing the next guy to curse and swear at you.

I agree wholeheartedly.  I'll bet that a pretty printer could solve all
these style complaints quite easily, though.  Just filter any source code
which you have to modify, and you will be able to read it in your
preferred style.

> Cheers,
> Woody

> p.s. Once again, the comments are not directed at GLENN.  They are directed
> at postscript programmers in general.  The GREEN book just happend to be
> a handy spot to grab the examples from.  I don't recommend following
> the style examples in the GREEN book, though otherwise the code is good.

I fear that this discussion is about to get religious (as if it hasn't
already).  Note that there are relatively minor changes to Woody's code
to bring it to what I consider the "proper" indentation style.  In fact,
it boils down to how far the braces should be indented and where the comment
containing the arguments go.

-David Jedlinsky
Digital Equipment Corporation   | He who dies with the most toys is dead.
dcj@decvax.dec.com              | 
...!decwrl!decvax!dcj           | 
.
.
.
.
.
.
.
.
.
.
.
.
.
. inews fodder