Path: utzoo!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!execu!sequoia!rpp386!woody
From: woody@rpp386.cactus.org (Woodrow Baker)
Newsgroups: comp.lang.postscript
Subject: Re: indentation style
Summary: more indents
Message-ID: <17880@rpp386.cactus.org>
Date: 7 Feb 90 05:23:47 GMT
References: <17807@rpp386.cactus.org> <9002040147.AA16999@en.ecn.purdue.edu> <45829@wlbr.IMSD.CONTEL.COM>
Organization: River Parishes Programming, Plano, TX
Lines: 162


Here are some examples, that I hope will help.

I have recieved several reqests for my address, in reference to the Password
resetter.  It seems that I must not have included it or something:

Woody Baker
Rt.1 Box I
Manor, Tx. 78653


 
 
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:
 
1. The { that matches the first }if is hidden at the end of the line
        72....
        
2. a quick look at the code, would lead you to match the }if
   brace with the { after the gt.  (If you can even find it)
 
3. it is not obvious what the }{ leading '}' here matches.  You
   have to work your way back up, line at a time to find that it
   matches the '{' after the gt.
   
4. related operations are not grouped together.
 
5. The comments are meaningless, and confuse the issue.
 
6. The function name does not stand out clearly by it's self.
 
 
It has the following advantage, if you can call it that.
 
It is compact in both the horizontal and vertical directions.
 
 
 
 
 
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
        
This code has the following drawbacks, if you could call them that.
 
It takes more vertical space than the prior code.
It takes more horizontal space than the prior code.
 
It has the following advantages.
 
 
 
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.
 
 
Another problem snippet
 
/MS { % multiple "show"
    counttomark 2 idiv {
       0 moveto show
    }repeat pop
    mark
}bind def
 
In this case, a look at the code, causes you to match the curly brace
just after the MS with the brace in front of the repeat.  This sends you
off hunting for the control for the repeat loop.  The hidden { is 
amost impossible to see.  Now, if this was hidden inside several more
blocks like this, and especially, if this define was nested inside of
a conditional, you could spend a lot of time analyzing the code in order
to understand it.
 
 
datastuff targetvalue eq {
      /MS { % multiple "show"
          counttomark 2 idiv {
              0 moveto show
          }repeat pop
        mark
     }bind def
     }{
     1 1 moveto
     }ifelse
     
     
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.  Personally, I'd
like to line 3 particular software authors up who worked on the compiler
I have to maintain, and either see how many of them, I could kill with one 
shot, or else get them between my headlights...
 
 
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.
       
t