Readable code (Was: Re: [H-GEN] Which is better?)

[Andrae Muys]

Harry Phillips wrote:

> [ Humbug *General* list - semi-serious discussions about Humbug and     ]
> [ Unix-related topics. Posts from non-subscribed addresses will vanish. ]
> 
> Russell Stuart wrote:
> 
>>
>> A fine recommendation, and I don't recall anyone arguing against it when
>> others said similar things in this thread.  Exactly what constitutes
>> "clean maintainable code" is possibly the real subject of this debate.
>>
> 
> On the subject of readable code, will I have to get used to reading code 
> that looks like this:
> 
> if (orient==east) {         
> if (x+radius>side) {
> if (clockwise) {orient=south;} else {orient=north;}
> }
> else {x=x+step;}
> }     
> else if (orient==south) {
> ....
> 
> 
> I find it alot easier to read:
> 
> if (orient==east)
>    {
>       if (x+radius>side)
>          {
>             if (clockwise) {orient=south;}
>             else {orient=north;}
>          }
>       else {x=x+step;}
>     }     
> else if (orient==south) {
> .....
> 
> 
> You can easily see what code is executed during which if statement. I 
> know doing it that way would create long lines for deeply nested if 
> statements (or for loops). Is that why most of the code I see is written 
> the first way?
> 
> BTW The above code was the "official solution" to our first assignment, 
> and it doesn't work as the assignment required.
> 
> The border check should have been:
>       if (x + step > side - radius) {...
> 

Oh dear, that code truely is appalling.  Are you sure it wasn't mangled 
by some HTML editor or something that stripped all leading whitespace?

Personally I would have written it

if (orient == east) {
   if (x + step > side - radius) {
     orient = clockwise ? south : north;
   } else {
     x += step;
   }
} else if (orient == south) {
...

However typographical concerns aside I'm going to guess that your 
lecturer has told you that this forms part of an object-orientated 
design.  It's not, try the following as a first refactoring (I'm going 
to guess some of the details).

class RotatingSprite {
   protected Polygon arena;
   protected Polygon sprite;
   protected Vector orientation;
   protected Axis rotationAxis;

   public void move(double step) {
     Polygon projectedForward =
         sprite.translate(orientation.scale(step));

     if (arena.contains(projectedForward)) {
       sprite = projectedForward;
     } else {
       sprite = sprite.rotate90(rotationAxis);
     }
   }
}

Which is readilly amenable to reasoning, and easilly confirmed correct.

There are a few experiments you can try which will teach you alot about 
programming, and what is possible (and what is desirable).  One very 
powerful lesson is writing a program with every function <=15 lines, and 
every class <=200lines (including the signature, parentheses, and using 
Sun's coding style).  It wasn't until I wrote a 10kloc program in this 
style that I finally groked OOP.

Now when coding in Java, I tend to leave my editor window set to 25-30 
lines and start to worry if I can't fit a function in the gap.  The 
extra lines tend to get used writing finer-grain error-handling, and the 
occasional inner-class.

Andrae Muys