Re: Case dependence and coding standards

[Georg Bauhaus <sb463ba@d2-hrz.uni-duisburg.de>]

Wesley Groleau <wesgroleau@despammed.com> wrote:
: Georg Bauhaus wrote:
:> Wesley Groleau <wesgroleau@despammed.com> wrote:
:> : Rational's pretty-printer as of 4.2 can vertically align all of:
:> : 
:> : :=  in  out  =>  :  --    (although it's still not perfect)
:> 
:> Tabular       layout  may     or      may     not     be      an
:> advantage     ,       I       am      still   eager   to
:> hear  arguments       ,       other   than    tired   programmers
:> liking        the     tidy    look    of      it      .
:> 
:> Georg
: 
: First, I mentioned that it can vertically align
: a certain set of symbols in source code, not all
: words in English prose.
: 
: Second, source code does not contain multiple
: words in prose style.

Yes, but it might still be read, see below.

: 
: Third,
: 
:     Variable : Variable_Type;  -- does the one thing
:     Another_Variable : Another_Variable_Type; -- does the other thing
: 
: IS a table in nature:
:   first column      - object name;
:   second column     - object type;
:   third column      - clarification;
:   column separators - ':' and '--'
: 
: Makes sense to me to write it like one:
: 
:     Variable         : Variable_Type;         -- number of doohickies built
:     Another_Variable : Another_Variable_Type; -- the current one built here
: 
: Same meaning to the compiler, MUCH easier on the human reader.

Here is where I'd like to see an argument, not a strong emphasis.
For another view (which empirically finds that layout-style guides
won't get you anywhere), see
http://www.cs.ukc.ac.uk/people/staff/lh8/pubs/pubist602s/MISRAC.pdf

There are different modes of reading source code.

One mode is when you use source code the way you look things up in
a table.  This might be the case when you vaguely remember an item,
and you want to look up the details, like the exact type or mode.
Another mode is when you start learning about an item and read all about it
from left to right, from top to bottom.

In the first case, I think tabular layout might help, but see below.
In the second case, the material to be read is closer to prose than
to a lookup table.

When I look at a time table, I can quickly scan a column for
2pm; when I am looking at the modes of subprogram parameters
vertically aligned in a column, what am I looking for? the
information seems incomplete to me, one column is not enough.
Still quickly finding just the modes might be useful in _some_ cases,
but then I'd prefer what is frequently done in print: make
them stand out using bold face type. As you have demonstrated,
humans can easily find out whether something is tabular in nature
_without_ "squarish" tabular layout, if "abstract" column separators
can easily be seen, like a ':'.

This might look like minor details, and I don't think these
particulars are important, but how about variable declarations,
consisting of name, type, constraints, and comment?  How about
constants, which add another column? Should a constraint that
might have three parts trigger tabular layout? Say you have

      north: Positive range 0 .. 90;  -- stops at north pole
      west: Positive range 0 .. 360; -- around the earth
      depth: Integer range -20_000 .. 0; -- below the sea

This could be formatted to look nicely ordered like

      north : Positive range       0 .. 90;   -- stops at north pole
      west  : Positive range       0 .. 360;  -- around the earth
      depth : Integer  range -20_000 .. 0;    -- below the sea

I wouldn't know how this could be extended consistently to include
constants (or longer identifiers). For a start, add:

      station_latitude: constant Mammoth_Footstep := 12;  -- where we are
 
If these four declarations should be grouped and alignments made at
':' etc, there will be a problem. 

After all I could argue that an if statement is a table in
nature too, like a case statement. Column borders: if, then, else, end.
Still, what kind of tabular layout is appropriate for an if statement?
I doubt programmers will like this idea.
Interestingly, it might be different with case statements where the cases
are short. But would you favour the use of "=>" after "when X"
as a column separator in the same way as ':' in variable declarations?
Sometimes I do that but usually I just use indentation and two or more
lines for a case, not a table. Here are some variations:

   declare
      X: Integer range 1..7;
   begin
      case X is
         when 1 => letsgo;
         when 2 .. 4 => come_on;
         when 5 => go_steady;
         when 6 | 7 => calm;
      end case;
   end;
   
   declare
      X: Integer range 1..7;
   begin
      case X is
         when 1      => letsgo;
         when 2 .. 4 => come_on;
         when 5      => go_steady;
         when 6 | 7  => calm;
      end case;
   end;

   declare
      X: Integer range 1..7;
   begin
      case X is
         when      1 => letsgo;
         when 2 .. 4 => come_on;
         when      5 => go_steady;
         when  6 | 7 => calm;
      end case;
   end;

   declare
      X: Integer range 1..7;
   begin
      case X is
         when   1    => letsgo;
         when 2 .. 4 => come_on;
         when   5    => go_steady;
         when 6 | 7  => calm;
      end case;
   end;

   declare
      X: Integer range 1..7;
   begin
      case X is
              when 1 => letsgo;
         when 2 .. 4 => come_on;
              when 5 => go_steady;
          when 6 | 7 => calm;
      end case;
   end;

: Notice that I never intended screwing up the comments as your
: strawman suggests.

It was not my intention to suggest that you screw up comments.

It's just that now and then I see source code where tabulation is
seemingly considered the essence of good coding. My eyes have to
jump "white gaps" of about 6em on the average on just about
every line. Now there _is_ (scientific) evidence that this is not
good for readers.

It might add to ones perspective to have a look a how Knuth's
C and Pascal programs look.


-- georg