At 01:54 AM 8/28/2003, Rick Duley wrote:
>Hi all
>
>Is there any move afoot to review the Ada Style Book?
>
>I have come to the conclusion that (when writing code in verbose style as I
>encourage students to do) we need to standardise indenting to avoid
>word-wrap when printing list files.  Take this for example:
>
>Ada.Text_Io.Put_Line(File => Log_File, Item => Event &
>Ada.Calendar.Day_Duration'Image(The_Seconds) & " - " &
>Ada.Calendar.Day_Number'Image(The_Day) &
>Ada.Calendar.Month_Number'Image(The_Month) &
>Ada.Calendar.Year_Number'Image(The_Year));
>
>As you can see, it gets a bit unwieldy :)  Much better, in my opinion, to
>realign it thus:
>
>Ada.Text_Io.Put_Line
>    (File => Log_File,
>     Item => Event
>             & Ada.Calendar.Day_Duration'Image(The_Seconds)
>             & " - "
>             & Ada.Calendar.Day_Number'Image(The_Day)
>             & Ada.Calendar.Month_Number'Image(The_Month)
>             & Ada.Calendar.Year_Number'Image(The_Year));
>
>which gives you a fair chance of getting it all on a page without
>word-wrap.  I can't see that this sort of thing is covered by the standard
>and it would be nice if the people who devise the "reformat" routines for
>IDEs had something standard to work to.

I think I prefer a more heuristic approach, rather than a single standard,
in this area.  My logic for formatting something like this (if I were doing
it by hand) would be:

1) Does the procedure call have only a single parameter (if so, it might
fit on a single line with no problem)?  No.

2) Put each parameter on a separate line.  Try putting the first parameter
on the same line as the procedure call, and align other parameters with the
first.  Do any lines exceed 79 characters (my limit)?  Yes (Item).

3) Change the formatting to put the first parameter on the next line with
standard indenting (as you suggest).  Does that make the problem go away?  No.

4) Break the long line at operator boundaries and align (as you
suggest).  Does that make the problem go away?  Yes (in this case).

5) If not, try changing the format to indenting the subsequent lines at the
standard indentation:

Ada.Text_IO.Put_Line (
     File => Log_File,
     Item => Event
         & Ada.Calendar.Day_Duration'Image (The_Seconds)
         & " - "
. . .

Does that make the problem go away?

6) If not, Break the remaining long lines as needed using these same
heuristics.

7) If that still does not help, change the standard indentation (from 4 to
3, for example).

For example, using this logic, if the maximum number of characters per line
in this example were 15, this statement could be formatted as follows:

Ada.Text_Io.
  Put_Line (
   File =>
    Log_File,
   Item =>
    Event &
     Ada.
      Calendar.
   Day_Duration'
    Image(
    The_Seconds)
           &
     " - " &
     Ada.
      Calendar.
     Day_Number'
      Image(
       The_Day)
           &
      Ada.
       Calendar.
   Month_Number'
    Image(
     The_Month)
           &
      Ada.
       Calendar.
    Year_Number'
     Image(
      The_Year)
              );

While this formatting is not very clean looking, it usually does not come
down that far.  The typical problem is where the statement is already
indented a bit due to the various block types ("case" statements, "if"
statements, "declare" blocks, etc.) and then a complex set of parameters
(including functions, as in this example) exist.  For that, my set of rules
would just move the indentation of the parameters back in the line, so the
rest of the statement would look fine, as follows:

                                                              Ada.Text_Io.
                                     Put_Line (
                                         File => Log_File,
                                         Item => Event        &
                                             Ada.Calendar.Day_Duration'Image(
                                                 The_Seconds) &
                                             " - "            &
                                             Ada.Calendar.Day_Number'Image(
                                                 The_Day)     &
                                             Ada.Calendar.Month_Number'Image(
                                                 The_Month)   &
                                             Ada.Calendar.Year_Number'Image(
                                                  The_Year));

And then I would hope the "case" within the "case" within the "if" within
the "if" within the "if" within the "case" within the "if" within the
"case" within the "if" within the "if" within the "declare" block within
the procedure within the package is not very long, and the indentation will
get back to a reasonable value.  Let's not get into a discussion of
complexity, and whether a given indentation value should ever get this
high.  While it does not happen all that often, per KSLOC, it happens at
least a few times in many complex programs.

Priorities have to be given to each of the formatting rules, so they can be
broken in the appropriate order.  Some would say that the line length is
not that important.  Others would want that to be the last rule to
break.  Some would say to do what I did up to the point where everything is
on a separate line, but aligned using the standard indentation value, and
then allow the line length to be violated.

I am pretty sure that a single standard, without acknowledging priorities,
and with no rules for exceptional cases, leads to problems.

Of course, then there are those (with young eyes) who say to just use a
6-point font (giving about 266 characters per line on a high resolution
screen). :-)

Roger Racine