Request for comments on simple Ada program

Request for comments on simple Ada program

[Maciej Sobczak]

Hi,

While playing with Ada and exercising its constructs, I have written the 
following classic Sieve of Eratosthenes:

with Ada.Text_IO;
with Ada.Integer_Text_IO;
use Ada.Text_IO;
use Ada.Integer_Text_IO;

procedure Primes is

    -- classic sieve
    procedure Print_Primes(Upper : in Positive) is
       Prime_Numbers : array(2..Upper) of Boolean := (others => True);
    begin
       for N in Prime_Numbers'Range loop
          if Prime_Numbers(N) then
             Put(N);
             New_Line;

             declare
                I : Positive := 2 * N;
             begin
                while I <= Prime_Numbers'Last loop
                   Prime_Numbers(I) := False;
                   I := I + N;
                end loop;
             end;
          end if;
       end loop;
    end Print_Primes;

    Upper_Limit : Positive;

begin
    Put("Enter the upper limit: ");
    Get(Upper_Limit);

    Print_Primes(Upper_Limit);
end Primes;


Now my question is: What would do do to make this code "better"?

Would you add comments? Loop labels? Change names? Is one-character name 
for the loop control variable considered OK?
Would you put the "sieving" part in a separate function? Maybe even more 
nested? Or maybe would you remove the separate function and put 
everything in the main function altogether?
Would you define a separate type for the array or is the anonymous type 
considered harmless?
Would you add more vertical whitespace? Or maybe it's already too much 
of them?
Would you use different scopes for variable declarations?

The question is not whether this program is correct, but rather what 
kind of pedantic touches would you apply to make it "better" (for your 
definition of "better", like more readable, etc.)?

I'm interested in style and what do you consider to be a *good* Ada 
code. Please do not hesitate to be as picky as you want - that's exactly 
the point of this post.

Note: This is not a homework, I'm a self-learner.

-- 
Maciej Sobczak : http://www.msobczak.com/
Programming    : http://www.msobczak.com/prog/

Re: Request for comments on simple Ada program

[Samuel Tardieu]

>>>>> "Maciej" == Maciej Sobczak <no.spam@no.spam.com> writes:

Maciej> I'm interested in style and what do you consider to be a
Maciej> *good* Ada code. Please do not hesitate to be as picky as you
Maciej> want - that's exactly the point of this post.

Ok, you want some nitpicking, here is some :)

After my signature, you can find the way I would have coded it. I
would have separated the prime numbers *computation* from the prime
number *display*. The computation may be reused in many contexts. What
if you now need to compute the primes in another part of your program
and store them in a file? It doesn't seem logical to have to modify
any part involved in prime numbers computation, especially if you want
to be able to test it in isolation.

My example is much more verbose than yours. However, it is also much
more reusable. I've also included an example of unit testing for the
Check_Primes procedure.

Of course, all that is a question of taste.

  Sam

with Ada.Text_IO;         use Ada.Text_IO;
with Ada.Integer_Text_IO; use Ada.Integer_Text_IO;
with Primes;              use Primes;

procedure Primes_Printer is

   procedure Print_Primes (Primes : Candidates_Array);
   --  Print all indices for which the value is True

   procedure Print_Primes_Up_To (Upper_Bound : Potential_Prime);
   --  Print all primes between 2 and Potential_Prime

   ------------------
   -- Print_Primes --
   ------------------

   procedure Print_Primes (Primes : Candidates_Array) is
   begin
      for N in Primes'Range loop
         if Primes (N) then
            Put (N); New_Line;
         end if;
      end loop;
   end Print_Primes;

   ------------------------
   -- Print_Primes_Up_To --
   ------------------------

   procedure Print_Primes_Up_To (Upper_Bound : Potential_Prime) is
      Primes : Candidates_Array (2 .. Upper_Bound) := (others => True);
   begin
      Check_Primes (Primes);
      Print_Primes (Primes);
   end Print_Primes_Up_To;

   Upper_Limit : Potential_Prime;

begin
   Put ("Enter the upper limit: ");
   Get (Upper_Limit);

   Print_Primes_Up_To (Upper_Limit);
end Primes_Printer;

package Primes is

   subtype Potential_Prime is Positive range 2 .. Positive'Last;

   type Candidates_Array is array (Potential_Prime range <>) of Boolean;
   pragma Pack (Candidates_Array);

   procedure Check_Primes (Candidates : in out Candidates_Array);
   --  Mark non prime numbers in Candidates by setting their entry
   --  to False. Entries must be previously set to True. The only
   --  exception is when Candidates'First is greater than 2: in this
   --  case, multiples of numbers between 2 and Candidates'First+1
   --  must contain False and will not be checked again.

end Primes;

package body Primes is

   ------------------
   -- Check_Primes --
   ------------------

   procedure Check_Primes (Candidates : in out Candidates_Array) is

      procedure Mark_Multiples (Multiplier : in Potential_Prime);
      --  Mark all multiples of Multiplier (not including itself) as
      --  being non primes.

      --------------------
      -- Mark_Multiples --
      --------------------

      procedure Mark_Multiples (Multiplier : in Potential_Prime)
      is
         M : Potential_Prime := 2 * Multiplier;
      begin
         while M <= Candidates'Last loop
            Candidates (M) := False;
            M := M + Multiplier;
         end loop;
      end Mark_Multiples;

   begin
      for N in 2 .. Candidates'Last loop
         if Candidates (N) then
            Mark_Multiples (N);
         end if;
      end loop;
   end Check_Primes;

end Primes;

with Ada.Text_IO; use Ada.Text_IO;
with Primes;      use Primes;

--  Test correctness of the Check_Primes function for primes up to 10_000

procedure Test_Primes is

   function Is_Prime (N : Potential_Prime) return Boolean;
   --  Check whether N can be divided by any number between 1 and N
   --  (exclusive).

   -------------
   -- Is_Prime --
   --------------

   function Is_Prime (N : Potential_Prime) return Boolean is
   begin
      for I in 2 .. N-1 loop
         if N rem I = 0 then
            return False;
         end if;
      end loop;
      return True;
   end Is_Prime;

   Primes : Candidates_Array (2 .. 10_000) := (others => True);

begin
   Check_Primes (Primes);
   for N in Primes'Range loop
      if Is_Prime (N) /= Primes (N) then
         Put_Line ("Error -- result for" & Potential_Prime'Image (N) &
                   " doesn't match");
         return;
      end if;
   end loop;
   Put_Line ("OK");
end Test_Primes;

Re: Request for comments on simple Ada program

[Samuel Tardieu]

>>>>> "Sam" == Samuel Tardieu <sam@rfc1149.net> writes:

Sam> It doesn't seem logical to have to modify any part involved in
Sam> prime numbers computation, especially if you want to be able to
Sam> test it in isolation.

Moreover (I forgot this point), you can now change the Check_Primes
procedure (in the Primes package body) without affecting the main
program, for example to use something else than Erathostene's
sieves. And the unit test will still be usable (and then becomes also
a regression test, which checks that you haven't broken anything).

  Sam
-- 
Samuel Tardieu -- sam@rfc1149.net -- http://www.rfc1149.net/sam

Re: Request for comments on simple Ada program

[Jacob Sparre Andersen]

Samuel Tardieu wrote:

Overall I like Samuel's version, but since we're picking nits, I'll
pick some in the comments (the code is as good as it gets) ...

>    procedure Print_Primes_Up_To (Upper_Bound : Potential_Prime);
>    --  Print all primes between 2 and Potential_Prime

... between 2 and Upper_Bound.

>    ------------------
>    -- Print_Primes --
>    ------------------
>
>    procedure Print_Primes (Primes : Candidates_Array) is

I use similar comments to separate/introduce procedures, but what do
we add by repeating the name of the procedure in the comment?  Except
for something which later can be different from the actual name of the
procedure?

Writing the function of the procedure in a comment is OK, although I
would like to keep all the non-checkable stuff outside the source
file.

Jacob (who believes that the optimal comment/code ratio is zero)
-- 
"I'm going as a barrel of toxic waste!"

Re: Request for comments on simple Ada program

[Samuel Tardieu]

>>>>> "Jacob" == Jacob Sparre Andersen <sparre@nbi.dk> writes:

Jacob> Jacob (who believes that the optimal comment/code ratio is
Jacob> zero)

It depends. Sometimes (particularily when doing embedded stuff), you
do have to comment the tricks you resort to. When I do some low-level
Ada or Forth programming for microcontrollers, some of the words (that
I need to optimize for performance) really need comments. If not for
me (the author of the code), at least for others.

What I do in general is reread every code I write one week later. Each
time I ask myself "why did I do this?", even for one second, I add a
comment. My experience shows that even when I go through the code one
year later, I have no question that are not already answered in the
comments.

  Sam
-- 
Samuel Tardieu -- sam@rfc1149.net -- http://www.rfc1149.net/sam

Re: Request for comments on simple Ada program

[Anders Wirzenius]

Samuel Tardieu <sam@rfc1149.net> writes:

> What I do in general is reread every code I write one week later. Each
> time I ask myself "why did I do this?", even for one second, I add a
> comment. My experience shows that even when I go through the code one
> year later, I have no question that are not already answered in the
> comments.
> 

Excellent way of working!

Once upon a time (early eighties) when I was a Fortran programmer, my
colleague and I used to start coding by writing a pseudo code. The
syntax for the pseudo code was Ada. Much of the Ada code was left in the
Fortran code as comments.

-- 
Anders

Re: Request for comments on simple Ada program

[Samuel Tardieu]

>>>>> "Jacob" == Jacob Sparre Andersen <sparre@nbi.dk> writes:

>> Print all primes between 2 and Potential_Prime

Jacob> ... between 2 and Upper_Bound.

Yeah, typo while coming up with an educative example :)

Jacob> I use similar comments to separate/introduce procedures, but
Jacob> what do we add by repeating the name of the procedure in the
Jacob> comment?

Visual effect. If you have an editor which emphasizes subprogram names
a lot, they might not be needed. However, putting them let anyone
browsing the code (even in plain text only) see the subprogram names
immediately.

  Sam
-- 
Samuel Tardieu -- sam@rfc1149.net -- http://www.rfc1149.net/sam

Re: Request for comments on simple Ada program

[Niklas Holsti]

Jacob Sparre Andersen wrote:

> Writing the function of the procedure in a comment is OK, although I
> would like to keep all the non-checkable stuff outside the source
> file.
> 
> Jacob (who believes that the optimal comment/code ratio is zero)

People differ. In my Ada code, the "comments" average 33% of 
non-blank lines (59% for package specs, 23% for package bodies, 
and note that I never repeat comments from specs in bodies). I 
still occasionally find it hard to *fully* understand code from a 
couple of years back. It's not the details -- I know what
N := N + 1 means by itself -- but the background assumptions, 
intentions, limitations, usage rules, interactions.

I put "comments" in quotes above, because I think that this is a 
bad case of mis-naming in programming language terminology. The 
word "comment" implies something skimpy, an addition, a note; in 
my view, what is needed is a rationale, description or motivation 
that is mainly written *before* the code itself.

As for keeping such text in separate design documents, I would do 
it if a customer demanded it, but I think it would be much harder 
to manage changes, versions and configurations accurately. Still, 
some very high-level descriptions are nice to keep apart from the 
source-code, if they are not outdated by day-to-day code changes.

-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
       .      @       .

Re: Request for comments on simple Ada program

[Jacob Sparre Andersen]

Niklas Holsti wrote:
> Jacob Sparre Andersen wrote:

>> Writing the function of the procedure in a comment is OK, although
>> I would like to keep all the non-checkable stuff outside the source
>> file.

>> Jacob (who believes that the optimal comment/code ratio is zero)
>
> In my Ada code, the "comments" average 33% of non-blank lines (59%
> for package specs, 23% for package bodies, and note that I never
> repeat comments from specs in bodies).

My numbers are 33% in specs and 18% in bodies (22% in total), but I
consider them to be too high.

My reason for mentioning what I believe is the optimal comment/code
ratio, is actually due to an article in ACM Queue, where the authors
used a code quality metric, which equalled more comments with higher
code quality.

> I still occasionally find it hard to *fully* understand code from a
> couple of years back. It's not the details -- I know what N := N + 1
> means by itself -- but the background assumptions, intentions,
> limitations, usage rules, interactions.

That can happen to me too - and to almost any other programmer too, I
suppose.

> I put "comments" in quotes above, because I think that this is a bad
> case of mis-naming in programming language terminology. The word
> "comment" implies something skimpy, an addition, a note; in my view,
> what is needed is a rationale, description or motivation that is
> mainly written *before* the code itself.

But I don't put the rationale in the source code.  The rationale is
kept in a separate file.  What I still do put in the source code - and
don't like putting there - is the abstracts for the subprograms and
packages.  But how can I easily cross-link the documentation (with the
abstracts) and the code (with the implementations)?  Should I cite the
package name/full subprogram specification in the documentation to
create the cross-link?  Or can somebody come up with a more elegant
solution?

> As for keeping such text in separate design documents, I would do it
> if a customer demanded it, but I think it would be much harder to
> manage changes, versions and configurations accurately. Still, some
> very high-level descriptions are nice to keep apart from the
> source-code, if they are not outdated by day-to-day code changes.

I always keep the design documents separate (when they exist ;-), but
I must admit that programming for research purposes is a bit different
from commercial software development.

Jacob
-- 
"Human beings just can't not communicate."

Re: Request for comments on simple Ada program

[Niklas Holsti]

Jacob Sparre Andersen wrote:
> Niklas Holsti wrote:
> 
>>...
> 
>>>Jacob (who believes that the optimal comment/code ratio is zero)

On a philosophical level, I agree with you -- writing "comments" 
is an extra burden, and one risks contradictions between the 
comments and the code (I recall an article long ago in SIGPLAN 
Notices with the title "Comments considered harmful" :-)

An ideal language should be expressive and readable enough to 
stand on its own. Unfortunately, Ada -- or, to be fair, the way I 
use Ada -- is still too low-level for that. Perhaps some future 
aspect-oriented language...

> My reason for mentioning what I believe is the optimal comment/code
> ratio, is actually due to an article in ACM Queue, where the authors
> used a code quality metric, which equalled more comments with higher
> code quality.

I agree that such a metric can be very misleading, because then 
you should measure the quality of the comments, too, which is 
impossible to automate. But I think anyone who has tried to reuse 
two code packages, one with (good) comments and the other without, 
must feel that there is *some* truth in the metric.

> But I don't put the rationale in the source code.  The rationale is
> kept in a separate file.  What I still do put in the source code - and
> don't like putting there - is the abstracts for the subprograms and
> packages.  But how can I easily cross-link the documentation (with the
> abstracts) and the code (with the implementations)?  Should I cite the
> package name/full subprogram specification in the documentation to
> create the cross-link?  Or can somebody come up with a more elegant
> solution?

There are some IDE-like commercial tools -- if memory serves, some 
sort of souped-up requirements databases + design tools + code 
generatorts with "automatic" document generation functions -- that 
claim to keep these cross-links for you. But burying my code in 
that sort of a monster machine makes me very nervous, and they 
aren't cheap either.

The conversation seems to be drifting towards Knuth's "literate 
programming". I think it is or was a good idea, but gave more 
benefit for Pascal than it would give for Ada, which can be more 
literate in itself. Perhaps the time is ripe for something like 
"checkable literate programming", modelled on SPARK, where the 
annotations/comments are readable and informative but also checkable?

-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
       .      @       .

Re: Request for comments on simple Ada program

[Brian May]

>>>>> "Samuel" == Samuel Tardieu <sam@rfc1149.net> writes:

    Samuel> procedure Print_Primes_Up_To (Upper_Bound : Potential_Prime) is
    Samuel> Primes : Candidates_Array (2 .. Upper_Bound) := (others => True);
    Samuel> begin
    Samuel> Check_Primes (Primes);
    Samuel> Print_Primes (Primes);
    Samuel> end Print_Primes_Up_To;

The disadvantage with this approach is if you want to generate a large
number of primes, the code:

a) needs to generate all primes before starting to display any.
b) needs additional memory to buffer all this primes first.

This might be significant in some applications - e.g. if output is to
go to web browser.

I would suggest an approach (if feasible) involving a function
"n := get_next_prime(n);" that calculates the next prime past n.

Of course, it depends on the requirements of the application using
this function if this is a problem or not. It might even be an
advantage in some cases.
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Request for comments on simple Ada program

[jimmaureenrogers]

Maciej Sobczak wrote:
> Hi,
>
> While playing with Ada and exercising its constructs, I have written the
> following classic Sieve of Eratosthenes:

In addition to the other suggestions you might also experiment with
using a packed array of boolean. The space savings from packing
the array will frequently result in an array that will be kept in the
CPU cache.

Even though it is less efficient to access individual bits, the program
execution speed, by my measurements, will increase by a factor of
approximately 3. The execution advantage is explained by the lack
of I/O overhead to off-cpu memory.

Jim Rogers

Re: Request for comments on simple Ada program

[tmoran]

>using a packed array of boolean. The space savings from packing
>the array will frequently result in an array that will be kept in the
>CPU cache.
>
>Even though it is less efficient to access individual bits, the program
>execution speed, by my measurements, will increase by a factor of
>approximately 3. The execution advantage is explained by the lack
>of I/O overhead to off-cpu memory.
  I'm surprised.  What size cache do you have and what value of Upper
did you use for timing?

Re: Request for comments on simple Ada program

[jimmaureenrogers]

tmoran@acm.org wrote:
> >using a packed array of boolean. The space savings from packing
> >the array will frequently result in an array that will be kept in the
> >CPU cache.
> >
> >Even though it is less efficient to access individual bits, the program
> >execution speed, by my measurements, will increase by a factor of
> >approximately 3. The execution advantage is explained by the lack
> >of I/O overhead to off-cpu memory.
>   I'm surprised.  What size cache do you have and what value of Upper
> did you use for timing?

My timings were done on a similar program which can be found at
http://shootout.alioth.debian.org/benchmark.php?test=nsieve&lang=gnat&id=0

My home system has an AMD 64 3400+ processor with 512 Mb L2 cache.
I ran my tests using Win XP Service Pack 1.

The program takes input from the command line and calculates 3
different values of Upper. It simply reports the number of primes
calculated during the run. The output for a command line value
of '9' is:

PROGRAM OUTPUT
==============
Primes up to  5120000   356244
Primes up to  2560000   187134
Primes up to  1280000    98610

Jim Rogers

Re: Request for comments on simple Ada program

[Martin Dowie]

jimmaureenrogers@worldnet.att.net wrote:
> My timings were done on a similar program which can be found at
> http://shootout.alioth.debian.org/benchmark.php?test=nsieve&lang=gnat&id=0
> 
> My home system has an AMD 64 3400+ processor with 512 Mb L2 cache.
> I ran my tests using Win XP Service Pack 1.
> 
> The program takes input from the command line and calculates 3
> different values of Upper. It simply reports the number of primes
> calculated during the run. The output for a command line value
> of '9' is:
> 
> PROGRAM OUTPUT
> ==============
> Primes up to  5120000   356244
> Primes up to  2560000   187134
> Primes up to  1280000    98610
> 
> Jim Rogers

Have you tried running with "-O2" instead of "-O3"? Apparently, "-O3" 
can cause some seemingly "perverse" effects.

Cheers

-- Martin

Re: Request for comments on simple Ada program

[tmoran]

> > >using a packed array of boolean. The space savings from packing
> > >the array will frequently result in an array that will be kept in the
> > >CPU cache.
> My home system has an AMD 64 3400+ processor with 512 Mb L2 cache.
> Primes up to  5120000   356244
  My Intel cpu with 1MB L2 cache runs your sieve almost twice as fast
unpacked up to 640K booleans, then it's down to 20% faster at 1.28 Million
booleans, and packed is 20% faster at 5 million.  At 20 million, where
it's out-of-cache in either case, unpacked is 15% faster than packed.

Re: Request for comments on simple Ada program

[Martin Krischik]

Maciej Sobczak wrote:

>     procedure Print_Primes(Upper : in Positive) is

I would use a self defined type instead of positive. You can optimise the
type. I.E. GNAT Positive is 32 bit but GNAT allows the definition of ranges
up to 64 bit:

type Primes_Type is 1 .. 2 ** 64 - 1;

That gives you a large range of possible values. Do Read my Wikibooks artice
on Fibonacci numbers:

http://en.wikibooks.org/wiki/Ada_Programming/Algorithms/Chapter_6

And perhaps you would like to add your code there too - once you optimised
it.

Martin 

-- 
mailto://krischik@users.sourceforge.net
Ada programming at: http://ada.krischik.com

Re: Request for comments on simple Ada program

[tmoran]

> I'm interested in style and what do you consider to be a *good* Ada
There is a wonderful book "Ada Quality and Style, Guidelines for
Professional Programmers".  A search at www.adaic.org finds the
Ada 95 version online.

Ada Quality and Style book discussion

[Anonymous Coward]

In article <ZqCdnSOLI6WepefeRVn-uw@comcast.com>, tmoran@acm.org wrote:
>> I'm interested in style and what do you consider to be a *good* Ada
> There is a wonderful book "Ada Quality and Style, Guidelines for
> Professional Programmers".  A search at www.adaic.org finds the
> Ada 95 version online.

Thanks for the recommendation.  I briefly skimmed through part of it.
I agree with most of it, but I do have some issues.

This was taken from 3.2.2:

   type Day is
      (Monday,    Tuesday,   Wednesday, Thursday,  Friday,
       Saturday,  Sunday);
   type Day_Of_Month    is range      0 ..    31;
   type Month_Number    is range      1 ..    12;
   type Historical_Year is range -6_000 .. 2_500;
   type Date is
      record
         Day   : Day_Of_Month;
         Month : Month_Number;
         Year  : Historical_Year;
      end record;

   In particular, Day should be used in preference to Days or
   Day_Type. 

I would not crunch all those type definitions together, especially
when some of them are multi-line definitions.  They should have a line
between them.

I also object to the guides comment advising against "Day_Type".  It's
a very good practice to suffix types with "_Type", "_Record", or
"_Array", so it's clear from the identifier what it refers to, and
also so you don't hijack a good variable name.  In the above case,
"Day" can no longer be used to name an object.

I'm surprized that section 2.1.5 permits:

   procedure Display_Menu_On_Screen (
         Title   : in     String;
         Options : in     Menus;
         Choice  :    out Alpha_Numerics
       );

The last line needlessly kills a line, and I always thought ending a
line with an open grouping symbol (like "(") is pretty ugly.

Re: Ada Quality and Style book discussion

[tmoran]

> I agree with most of it, but I do have some issues.
It agrees with me about 95% of the time, but somethings they did get wrong.
:)

Re: Ada Quality and Style book discussion

[Simon Wright]

Anonymous Coward <spam@spam.com> writes:

> I also object to the guides comment advising against "Day_Type".
> It's a very good practice to suffix types with "_Type", "_Record",
> or "_Array", so it's clear from the identifier what it refers to,
> and also so you don't hijack a good variable name.  In the above
> case, "Day" can no longer be used to name an object.

This is one of the more contentious style arguments. If you work on my
project, I will insist that you _don't_ stick these useless suffices
on. And I'm not sure that Day is a good variable name; if it's not
worth giving it a name which indicates its use, what's wrong with
plain D? (we were tempted to have a local style guideline that the
length of a name should be log2(lines of scope)).

If I work on your project, I'll abide by your rules, of course.

> I'm surprized that section 2.1.5 permits:
>
>    procedure Display_Menu_On_Screen (
>          Title   : in     String;
>          Options : in     Menus;
>          Choice  :    out Alpha_Numerics
>        );
>
> The last line needlessly kills a line, and I always thought ending a
> line with an open grouping symbol (like "(") is pretty ugly.

Now here I completely agree with you!

Re: Ada Quality and Style book discussion

[Martin Dowie]

Simon Wright wrote:
> Anonymous Coward <spam@spam.com> writes:
> 
> 
>>I also object to the guides comment advising against "Day_Type".
>>It's a very good practice to suffix types with "_Type", "_Record",
>>or "_Array", so it's clear from the identifier what it refers to,
>>and also so you don't hijack a good variable name.  In the above
>>case, "Day" can no longer be used to name an object.
> 
> 
> This is one of the more contentious style arguments. If you work on my
> project, I will insist that you _don't_ stick these useless suffices
> on. And I'm not sure that Day is a good variable name; if it's not
> worth giving it a name which indicates its use, what's wrong with
> plain D? (we were tempted to have a local style guideline that the
> length of a name should be log2(lines of scope)).

I'm with Simon on this one. "Today" or "This_Day" or "The_First_Day" are 
better variable names...

...however, there are times when there are name clashes and (for no good 
reason that I can think of) Ada can't tell the difference between a 
types name and, say, an enumerate.

So, instead of appending the ugly "_Type", I prefer to use the English 
as my inspiration and prefix "A_" or "An_". Types are after all 
"indefinite articles". Objects are "definite articles".

E.g.

    My_New_Saab : A_Car;

Which can be read "My new Saab is a Car".

Cheers

-- Martin

Re: Ada Quality and Style book discussion

[Anonymous Coward]

In article <dlelkn$g6l$1@nwrdmz03.dmz.ncs.ea.ibs-infra.bt.com>, 
Martin Dowie wrote:
> 
> I'm with Simon on this one. "Today" or "This_Day" or "The_First_Day"
> are better variable names...

"Today" and "The_First_Day" are better variable names if the objects
really have those meanings; but "This_Day" is lousy, because any noun
(and non-boolean objects should be nouns) can follow "This_", which is
completely meaningless.  "_Type" is meaningful, because it indicates a
user defined type.  

"A_" and "An_" is almost as meaningless as "This_", because *most*
objects in a system are singular.  It's far less noise to make plural
objects to stand out by adding an "s" or "_Array" or "_List".

> ...however, there are times when there are name clashes and (for no
> good reason that I can think of) Ada can't tell the difference
> between a types name and, say, an enumerate.
> 
> So, instead of appending the ugly "_Type", I prefer to use the
> English as my inspiration and prefix "A_" or "An_". Types are after
> all "indefinite articles". Objects are "definite articles".
> 
> E.g.
> 
>     My_New_Saab : A_Car;
> 
> Which can be read "My new Saab is a Car".

The project I worked on that banned "_Type" also tried to encourage
developers to choose identifiers that make a complete grammatically
correct english sentence, as if it were more important that
non-technical folks could read the code than the maintainers.  

It didn't work out too well, because when you make an english sentence
in one usage, the same identifers make the code look like crap where
an english sentence doesn't exist.  ie.

   function compute_altitude (using : in temperature;
                              and   : in dew_point;
                              with  : in pressure) return altitude is
   begin

      return (using + and / with);

   end compute_altitude;

Obviously that's a bogus formula.. but it should be clear from this
that making code read like english down to the point of including
articles like "and", "with", "is", asks for disaster.  Some folks
really complied with this direction, and wrote code like that function
above - I'm not joking.

Re: Ada Quality and Style book discussion

[Martin Dowie]

Anonymous Coward wrote:
> "Today" and "The_First_Day" are better variable names if the objects
> really have those meanings; but "This_Day" is lousy, because any noun
> (and non-boolean objects should be nouns) can follow "This_", which is
> completely meaningless.  "_Type" is meaningful, because it indicates a
> user defined type.  

It's just 2 or 3 characters longer than it needs to be! ;-)



> "A_" and "An_" is almost as meaningless as "This_", because *most*
> objects in a system are singular.  It's far less noise to make plural
> objects to stand out by adding an "s" or "_Array" or "_List".

I'm not advocating "A(n)_" for objects - just types. I don't have a 
problem with "An_Array_Of_Foos".



>    function compute_altitude (using : in temperature;
>                               and   : in dew_point;
>                               with  : in pressure) return altitude is
>    begin
> 
>       return (using + and / with);
> 
>    end compute_altitude;

Well that's just a pants idea - what if you have 7 parameters "and_also" 
"and_also_again"????

Re: Ada Quality and Style book discussion

[Georg Bauhaus]

On Thu, 2005-11-17 at 04:49 +0000, Anonymous Coward wrote:
>  "_Type" is meaningful, because it indicates a
> user defined type.  

This alone will justify names like XYZ_Package
UVW_Procedure, etc.

  package Chips is new Vegetable_Package (Potato);

Or, to emphasize the issue

  package Chips is new Vegetable_package (Potato);

  procedure ssq is
    new Summing_procedure(vs, square'Access);

Consider suffixes _package, _procedure, ... all over the place...


-- Georg 

Re: Ada Quality and Style book discussion

[Stephen Leake]

Georg Bauhaus <bauhaus@futureapps.de> writes:

> On Thu, 2005-11-17 at 04:49 +0000, Anonymous Coward wrote:
>>  "_Type" is meaningful, because it indicates a
>> user defined type.  
>
> This alone will justify names like XYZ_Package
> UVW_Procedure, etc.

No, it doesn't, because package names never collide with object names.

Type names do collide with object names; that's the _only_ reason they
need a special naming convention.

-- 
-- Stephe

Re: Ada Quality and Style book discussion

[Georg Bauhaus]

On Thu, 2005-11-17 at 07:37 -0500, Stephen Leake wrote:
> Georg Bauhaus <bauhaus@futureapps.de> writes:
> 
> > On Thu, 2005-11-17 at 04:49 +0000, Anonymous Coward wrote:
> >>  "_Type" is meaningful, because it indicates a
> >> user defined type.  
> >
> > This alone will justify names like XYZ_Package
> > UVW_Procedure, etc.
> 
> No, it doesn't, because package names never collide with object names.

I'm not sure I understand what particular collision you have in
mind. An artificial example,

   package Y is new X_Package;

   ...

   package Collide is

     type T_Type is range 1 ..99;

     Y: T_Type := 42;

   end Collide;

   ...

   use Collide;

   package H_Package is new G_Package(T_Type, Y, Y);  -- Bang! 

where G_Package is declared

with X_Package;
generic
   type Some_Type is range <>;
   with package Some_Package is new X_Package(<>);  -- package name
   Some_Variable: in out Some_Type;  -- object name
package G_Package is ...

Here, adopting the convention and adding a _Package suffix,

  package Y_Package is new X_Package;

will allow resolving the naming conflict.
But is Y_package the best name?
Or should I just qualify Collide.Y?

> Type names do collide with object names; that's the _only_ reason they
> need a special naming convention.

Re: Ada Quality and Style book discussion

[Stephen Leake]

Georg Bauhaus <bauhaus@futureapps.de> writes:


> <example snipped>
>
> Here, adopting the convention and adding a _Package suffix,
>
>   package Y_Package is new X_Package;
>
> will allow resolving the naming conflict.

yes, but see below.

> But is Y_package the best name? 

no.

> Or should I just qualify Collide.Y?

Yes. 

You introduced a name collision by the 'use' clause; that can always
cause name collisions. The proper solution in that case is to use the
qualified name.


-- 
-- Stephe

Don't use the "use" clause

[Anonymous Coward]

In article <ulkzmsw5v.fsf@acm.org>, Stephen Leake wrote:
> 
> You introduced a name collision by the 'use' clause; that can always
> cause name collisions. The proper solution in that case is to use
> the qualified name.

I agree.  I personally take it an extreme step further, and never use
use clauses anywhere.  They shouldn't even be in the language.  Every
Ada project I've worked on that had a coding standard banned the use
clause, and rightly so.  

I don't only oppose it because of the ambiguity, but even when there
is no ambiguity, it's a severe inconvenience to have to grep a large
tree to hunt down a declaration.  Then to possibly get multiple hits
and have to compare two lists of packages to discover which hit is the
correct one.  By the time you make it to the declaration you're
looking for, you've forgotten why you need to look at it :)

Clearly the typing time saved by the use clause cannot possibly offset
the time lost on all the resulting code searches.

Re: Don't use the "use" clause

[Ed Falis]

On Sat, 19 Nov 2005 15:28:25 -0500, Anonymous Coward <spam@spam.com> wrote:

> I don't only oppose it because of the ambiguity, but even when there
> is no ambiguity, it's a severe inconvenience to have to grep a large
> tree to hunt down a declaration.  Then to possibly get multiple hits
> and have to compare two lists of packages to discover which hit is the
> correct one.  By the time you make it to the declaration you're
> looking for, you've forgotten why you need to look at it

If you were using a modern editor, with Ada cross-referencing, you  
wouldn't have this problem.  GPS, emacs Ada mode, ObjectAda and quite a  
few others provide this.

- Ed

Re: Don't use the "use" clause

[David Emery]

I've been in the middle of several debates on this.  My personal strong belief and experience has been that qualified names are very useful in comprehension, particularly trying to grasp the 'big picture' of software structure.  

So in one previous life, when handed a package that did not have qualified names in it, the first thing I'd do is add the qualified names.  

it's possible to construct programming environments that can show you the unambiguous source for each name/operator.  But such information is transient, it only lasts for as long as you have the mouse/etc there.  Often I'm sufficiently "Luddite" that I print out and scribble over hardcopies of programs.

			dave

Ed Falis wrote:
> On Sat, 19 Nov 2005 15:28:25 -0500, Anonymous Coward <spam@spam.com> wrote:
> 
>> I don't only oppose it because of the ambiguity, but even when there
>> is no ambiguity, it's a severe inconvenience to have to grep a large
>> tree to hunt down a declaration.  Then to possibly get multiple hits
>> and have to compare two lists of packages to discover which hit is the
>> correct one.  By the time you make it to the declaration you're
>> looking for, you've forgotten why you need to look at it
> 
> 
> If you were using a modern editor, with Ada cross-referencing, you  
> wouldn't have this problem.  GPS, emacs Ada mode, ObjectAda and quite a  
> few others provide this.
> 
> - Ed

Re: Don't use the "use" clause

[Ed Falis]

On Mon, 21 Nov 2005 12:36:47 -0500, David Emery <demery@cox.net> wrote:

> it's possible to construct programming environments that can show you  
> the unambiguous source for each name/
> operator.  But such information is transient, it only lasts for as long  
> as you have the mouse/etc there.  Often I'm sufficiently "Luddite" that  
> I print out and scribble over hardcopies of programs.
>


I think this is a case of "your mileage may vary", or "you can't argue  
taste".  I've never missed fully qualified names (and dislike those cute  
little package renamings to acronyms - which I really hate).  The cost of  
full qualification (particularly when the environment supports  
cross-referencing) is cluttered code.

But we can all agree to disagree, provided we follow the coding  
conventions of our employers ;-)

- Ed

Re: Don't use the "use" clause

[David Trudgett]

"Ed Falis" <falis@verizon.net> writes:

>
> But we can all agree to disagree, provided we follow the coding
> conventions of our employers ;-)

Can we agree to disagree even if we don't follow the coding
conventions of our employers? ;-)

David



-- 

David Trudgett
http://www.zeta.org.au/~wpower/

Beware of bugs in the above code; 
I have only proved it correct, not tried it.
  
    -- Donald Knuth (1977)

Re: Don't use the "use" clause

[Ed Falis]

On Mon, 21 Nov 2005 17:21:09 -0500, David Trudgett  
<wpower@zeta.org.au.nospamplease> wrote:

> Can we agree to disagree even if we don't follow the coding
> conventions of our employers?

Works for me with my own code ;-)

Re: Don't use the "use" clause

[Anonymous Coward]

In article <op.s0lunzyd5afhvo@localhost>, 
Ed Falis wrote:
> 
> I think this is a case of "your mileage may vary", or "you can't
> argue taste".

I would agree that you can't argue taste purely on the merits of
personal preference, but as soon as you bring in the bu$iness case,
the answer becomes clear.  Egocentrics who can't see outside
themselves cannot effectively argue from the perspective of analysing
code written by others.

The cost of having too much information is *cheaper* than the cost of
having too little information, because the trained eye can very
quickly ignore what is not interesting.  It's certainly not equally
fast to find missing information.

To test that claim, simply go to a web site with banner ads.  Can you
find the interesting content quicker than you can mouse around and
click the Firefox "ad block" tab on the unwanted ad?  Probably.  I
don't even see the banner ads anymore.

I know first hand from a project that had an unenforced prohibition on
use clauses, for which the company lost copious manhours due to
undisciplined programmers abusing the use clause (when combined with
crappy tools).  Superior tools would have reduced thoses losses
substantially.  But then you would have to consider the cost of the
better tools themselves.  With the hypothetically best tools, and
assuming they are better than a mouse over cross reference which will
also accommodate code reviews, you're only breaking even at best.

Re: Don't use the "use" clause

[Ed Falis]

On Mon, 21 Nov 2005 19:15:55 -0500, Anonymous Coward <spam@spam.com> wrote:

> I would agree that you can't argue taste purely on the merits of
> personal preference, but as soon as you bring in the bu$iness case,
> the answer becomes clear.

Actually, is doesn't become as clear as you think.  My company uses use  
clauses, and find the approach to have merit.

> Egocentrics who can't see outside
> themselves cannot effectively argue from the perspective of analysing
> code written by others.

Is that ad hominem?

>
> The cost of having too much information is *cheaper* than the cost of
> having too little information, because the trained eye can very
> quickly ignore what is not interesting.  It's certainly not equally
> fast to find missing information.

If the information is easy to hand, this argument evaporates, and clutter  
does have a cost.


> I know first hand from a project that had an unenforced prohibition on
> use clauses, for which the company lost copious manhours due to
> undisciplined programmers abusing the use clause (when combined with
> crappy tools).  Superior tools would have reduced thoses losses
> substantially.  But then you would have to consider the cost of the
> better tools themselves.  With the hypothetically best tools, and
> assuming they are better than a mouse over cross reference which will
> also accommodate code reviews, you're only breaking even at best.

No, there's the losing the forest for the trees effect as well.  I've  
consulted with many, many Ada projects that use the "no use clause"  
prohibition and seen an awful lot of wasted time due to people getting  
lost in the course of maintaining their code base.  And I've also seen  
companies that allow use of the clause that operated well.  This is all  
anecdotal evidence.  Tools don't cost very much compared to lost  
productivity.  I've been doing Ada since 1981, and have seen plenty of  
stupid conventional wisdom.  IMO, of course.

Let me tell you about the 300 line subprogram that was presented to me.   
The customer couldn't understand why certain code was never executed.  The  
nesting levels of the statement list were pushing 7 or 8 levels deep.   
After looking at it for a bit, it became clear that the subprogram was  
written so that the code in question could not be executed.  I rewrote the  
subprogram in 40 lines.  The sheer dirtiness and complexity (ie noise) of  
the code was the problem, and the several people who reviewed it couldn't  
determine that the subprogram was doing exactly what it was told to.   
Noise overwhelmed their ability to analyze what was happening.  An extreme  
case, but not all that uncommon in code I've seen.

- Ed

Re: Don't use the "use" clause

[tmoran]

> ...  and clutter does have a cost.
I wonder what happens if you fit the identifier or word frequencies vs
lengths in an Ada source to Zipf's law (or a variant, eg
http://www.ling.lu.se/persons/Joost/Texts/studling.pdf)  It would seem
likely that matching human language statistics would be "good".  Anyone
tried this?

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Sat, 19 Nov 2005 20:28:25 GMT, Anonymous Coward wrote:

> In article <ulkzmsw5v.fsf@acm.org>, Stephen Leake wrote:
>> 
>> You introduced a name collision by the 'use' clause; that can always
>> cause name collisions. The proper solution in that case is to use
>> the qualified name.
> 
> I agree.  I personally take it an extreme step further, and never use
> use clauses anywhere.  They shouldn't even be in the language.  Every
> Ada project I've worked on that had a coding standard banned the use
> clause, and rightly so.  

No, name collisions better be prevented by making "use" illegal when it
hides anything.

BTW, what about banning implicit "use" of "Standard"? Care to write an AI
to make Integer, "+", "-" etc invisible? (:-))

> I don't only oppose it because of the ambiguity, but even when there
> is no ambiguity, it's a severe inconvenience to have to grep a large
> tree to hunt down a declaration.

IDE should have "go to declaration" button.

> Then to possibly get multiple hits
> and have to compare two lists of packages to discover which hit is the
> correct one.  By the time you make it to the declaration you're
> looking for, you've forgotten why you need to look at it :)

It is no matter "where", "what" does matter. If you need to frequently
browse sources to determine "what", then the program is poorly designed.

> Clearly the typing time saved by the use clause cannot possibly offset
> the time lost on all the resulting code searches.

What about the time spent on reading something like A.B.C.D.E.F.G.H?

If I were a "use"-hater I would propose a reverse notation for fully
qualified names: H of G of F of E of D of C of B of A (at least for those
who reads programs from left to right it would be a great help! (:-))

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Simon Wright]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> writes:

> What about the time spent on reading something like A.B.C.D.E.F.G.H?

As used in the GNAT sources, for example ..

  package SSE renames System.Storage_Elements;

within a reasonably short local scope (a page or two, perhaps).

Re: Don't use the "use" clause

[Anonymous Coward]

In article <1ef4kvy6kdkwz.oqmb8acj5joo.dlg@40tude.net>, 
Dmitry A. Kazakov wrote:
> 
> No, name collisions better be prevented by making "use" illegal when
> it hides anything.

The use clause is barred by coding standards for a good reason, and I
don't think it's necessarily name collisions that drive this rule.
Programmers are forced to resolve name collisions, with or without the
USE clause.  The use clause is banned because it makes code unreadable
and difficult to use.  As Joel Spolsky said, travel should be minimal
when interpretting a line of code.  Fully qualified naming is a better
style because you know immediately, from the code itself, where the
identifier lives.  And if you need to see the declaration, you know
immediately where to go.

> BTW, what about banning implicit "use" of "Standard"? Care to write
> an AI to make Integer, "+", "-" etc invisible? (:-))

The "use type" clause is a different beast, and I do not object to its
use; nor is it banned in any coding standard I've read.

> IDE should have "go to declaration" button.

I agree, but not all IDEs have that luxery.  The last IDE I worked in
had the option, but it was broken.  My current environment is emacs,
which doesn't offer that feature by itself.  I've only seen it when
emacs is paired with Apex.  Even under the best tools, where a
mouseover might reveal the home for some declaration, it's still poor
style to not have that information in the text, so the reader doesn't
have to mouse around compulsively, as the keyboard is faster than the
mouse.

>> Then to possibly get multiple hits and have to compare two lists of
>> packages to discover which hit is the correct one.  By the time you
>> make it to the declaration you're looking for, you've forgotten why
>> you need to look at it :)
> 
> It is no matter "where", "what" does matter. If you need to
> frequently browse sources to determine "what", then the program is
> poorly designed.

Certainly not.  I would say just the opposit.  If you're repeating
information from your declaration in your identifiers, then you've
created a maintenance problem by introducing too much noise, also
forcing identifiers to change whenever the declaration changes.  A
good design doesn't repeat this information.

>> Clearly the typing time saved by the use clause cannot possibly offset
>> the time lost on all the resulting code searches.
> 
> What about the time spent on reading something like A.B.C.D.E.F.G.H?

If you have something like that, then there's something wrong with the
architecture of your project.  A user should not need visibility into
such a deep level within an external component.

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Sat, 19 Nov 2005 23:40:46 GMT, Anonymous Coward wrote:

> In article <1ef4kvy6kdkwz.oqmb8acj5joo.dlg@40tude.net>, 
> Dmitry A. Kazakov wrote:
>> 
>> No, name collisions better be prevented by making "use" illegal when
>> it hides anything.
> 
> The use clause is barred by coding standards for a good reason, and I
> don't think it's necessarily name collisions that drive this rule.

What else then?

> Programmers are forced to resolve name collisions, with or without the
> USE clause.

No. Don't refer to conflicting names and the compiler won't object. This is
IMO bad.

> The use clause is banned because it makes code unreadable
> and difficult to use.  As Joel Spolsky said, travel should be minimal
> when interpretting a line of code.  Fully qualified naming is a better
> style because you know immediately, from the code itself, where the
> identifier lives.  And if you need to see the declaration, you know
> immediately where to go.

How so? Why should I care about the declaration/definition places? What
should be a fully qualified name of a dispatching call to a 10-times
overridden primitive operation, provided that 5 of them were private? The
first, the last, one in the middle?

>> BTW, what about banning implicit "use" of "Standard"? Care to write
>> an AI to make Integer, "+", "-" etc invisible? (:-))
> 
> The "use type" clause is a different beast, and I do not object to its
> use; nor is it banned in any coding standard I've read.

What is the difference between "+" and "Add"?

>>> Then to possibly get multiple hits and have to compare two lists of
>>> packages to discover which hit is the correct one.  By the time you
>>> make it to the declaration you're looking for, you've forgotten why
>>> you need to look at it :)
>> 
>> It is no matter "where", "what" does matter. If you need to
>> frequently browse sources to determine "what", then the program is
>> poorly designed.
> 
> Certainly not.  I would say just the opposit.  If you're repeating
> information from your declaration in your identifiers, then you've
> created a maintenance problem by introducing too much noise, also
> forcing identifiers to change whenever the declaration changes.  A
> good design doesn't repeat this information.

It seems that you are arguing my point. Name prefix is that noise you are
talking about.

>>> Clearly the typing time saved by the use clause cannot possibly offset
>>> the time lost on all the resulting code searches.
>> 
>> What about the time spent on reading something like A.B.C.D.E.F.G.H?
> 
> If you have something like that, then there's something wrong with the
> architecture of your project.  A user should not need visibility into
> such a deep level within an external component.

That might be true, but irrelevant because the implementation of H should
know A and A.B and A.B.C etc. According to your theory within H anything
from G must be referred as A.B.C.D.E.F.G.X!

Now if you aren't going to argue against child packages, consider "use A"
as an ad-hoc parent specification.

BTW, one probably could even remove "use" from the language allowing
multiple parents instead.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Jeffrey R. Carter]

Dmitry A. Kazakov wrote:

> BTW, what about banning implicit "use" of "Standard"? Care to write an AI
> to make Integer, "+", "-" etc invisible? (:-))

There is no implicit "use" of Standard. Rather, everything is part of Standard. 
For example, a library-level package P may be explicitly referred to as Standard.P.

-- 
Jeff Carter
"I'm a kike, a yid, a heebie, a hook nose! I'm Kosher,
Mum! I'm a Red Sea pedestrian, and proud of it!"
Monty Python's Life of Brian
77

Re: Don't use the "use" clause

[Stephen Leake]

Anonymous Coward <spam@spam.com> writes:

> In article <ulkzmsw5v.fsf@acm.org>, Stephen Leake wrote:
>> 
>> You introduced a name collision by the 'use' clause; that can always
>> cause name collisions. The proper solution in that case is to use
>> the qualified name.
>
> I agree.  I personally take it an extreme step further, and never use
> use clauses anywhere.  They shouldn't even be in the language.  Every
> Ada project I've worked on that had a coding standard banned the use
> clause, and rightly so.  

Hmm. Even for operators?

A := B + C; 

should work when A, B, C are Cartesian Vectors, not just scalars.

And a use clause in a small function can easily improve readability.

> I don't only oppose it because of the ambiguity, but even when there
> is no ambiguity, it's a severe inconvenience to have to grep a large
> tree to hunt down a declaration.  

As others have said, get a real editor.

> Clearly the typing time saved by the use clause cannot possibly offset
> the time lost on all the resulting code searches.

It's not the time typing I'm worried about, it's the time reading and
understanding.

-- 
-- Stephe

Re: Don't use the "use" clause

[Anonymous Coward]

In article <uwtj4xc6j.fsf@acm.org>, Stephen Leake wrote:
> 
> Hmm. Even for operators?
> 
> A := B + C; 
> 
> should work when A, B, C are Cartesian Vectors, not just scalars.
>
> And a use clause in a small function can easily improve readability.

That's what the "use type" clause is for.  I have no objection to the
use type clauses.  I use them myself, and coding standards always
accommodate them.

>> I don't only oppose it because of the ambiguity, but even when there
>> is no ambiguity, it's a severe inconvenience to have to grep a large
>> tree to hunt down a declaration.  
> 
> As others have said, get a real editor.

The version of emacs they've installed at work does not have this
capability, and I'm stuck with what they provide; but it wouldn't
matter anyway.  Even with that feature (which I've had on previous
projects), it wouldn't be worth it to constantly search like that,
when disciplined Ada programmers can simply follow the coding standard
and fully qualify external identifiers.

As a beginner I was tempted to use the use, but after I was forced to
fully qualify, I've discovered that it's much easier to read code from
others as well as old code of my own.  I would never go back, even if
Emacs had a mouseover cross reference.

>> Clearly the typing time saved by the use clause cannot possibly
>> offset the time lost on all the resulting code searches.
> 
> It's not the time typing I'm worried about, it's the time reading
> and understanding.

In that case the time you're worried about is what's reduced by fully
qualifying your names.  If you get the information as fast as you can
read it, you know what's going on faster than you can even reach for
your mouse.  You just cannot beat instantaneously knowing which names
are internal and which are not, and where they come from.

There is one case where I might be willing to tolerate the use clause
on a project.  If an editor existed that would fully qualify the names
(inline) as it loads the buffer so I wouldn't even need to hover over
them with a mouse, and the project supported such a tool, then it
wouldn't matter to me either way whether I had to read code that used
use clauses.  AFAIK, no such tool exists, or at least it's certainly
not mainstream.

A better approach would be to have the controlled code checked in
without use clauses, and if some hacker wants the package names
hidden, or other hidden information for that matter, then it would be
easier to make that a check out for browse option.

At one point I worked on a project that did not enforce their
prohibition on the use clause.  They simultaneously mandated a lousy
Windows-based tool set, which did not have cross referencing, and to
worsen things, grep was not provided either.  So we had to search
using the crappy native Microsoft search tool, which does not support
regular expressions.  The folks on that project who used use clauses
needlessly robbed me of copious manhours.

Re: Don't use the "use" clause

[Pascal Obry]

Anonymous Coward a �crit :
> I don't only oppose it because of the ambiguity, but even when there
> is no ambiguity, it's a severe inconvenience to have to grep a large
> tree to hunt down a declaration.  Then to possibly get multiple hits
> and have to compare two lists of packages to discover which hit is the
> correct one.  By the time you make it to the declaration you're
> looking for, you've forgotten why you need to look at it :)

Or you use GPS :) Or any decent IDE that can jump to the rigth place for
you !

Pascal.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|              http://www.obry.net
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595

Re: Don't use the "use" clause

[Jeffrey R. Carter]

Anonymous Coward wrote:

> I agree.  I personally take it an extreme step further, and never use
> use clauses anywhere.  They shouldn't even be in the language.  Every
> Ada project I've worked on that had a coding standard banned the use
> clause, and rightly so.  

There is some justification for this. SPARK, for example, does not have the use 
clause (but does have the use type clause).

I tend to work from the idea of what the reader should know. I expect my reader 
to know Ada, and as such to be familiar with the standard library, so there's no 
real problem with using Ada.Text_IO. On a specific project, if there's a 
standard library used on the project, people working on the project should be 
familiar with the library, and using the library packages should not be a 
problem. However, I don't expect everyone to be familiar with the entire system, 
so application-specific packages should generally not be used.

-- 
Jeff Carter
"I'm a kike, a yid, a heebie, a hook nose! I'm Kosher,
Mum! I'm a Red Sea pedestrian, and proud of it!"
Monty Python's Life of Brian
77

greptree

[lou]

I agree that the use clause obscures the source of a function.
However I will use it for overloaded operators and for project
wide type definitions.

> I don't only oppose it because of the ambiguity, but even when there
> is no ambiguity, it's a severe inconvenience to have to grep a large
> tree to hunt down a declaration. 

I use the following script to search the code tree when gps won't work, 
for example on imported code.

#!/bin/bash
key=$1
src=$2

for i in `find $src -type f | gawk '{gsub(" ","###",$0);print $0}'`
   do
   f=`echo $i | gawk '{gsub("###"," ",$0);print $0}'`
   grep -in $key "$f" | gawk -v var="$f" '{print var":"$0}'
   done

Re: greptree

[Simon Wright]

lou <tlou@fireball.home> writes:

> I use the following script to search the code tree when gps won't
> work, for example on imported code.

I don't see why GPS (gnatfind, I think, under the hood) wouldn't work,
provided you can compile the imported code? (at least make a start on
compiling it, anyway, so there's enough .ali to do browsing).

Re: greptree

[Björn Persson]

lou wrote:
> I use the following script to search the code tree when gps won't work, 
> for example on imported code.
> 
> #!/bin/bash
> key=$1
> src=$2
> 
> for i in `find $src -type f | gawk '{gsub(" ","###",$0);print $0}'`
>    do
>    f=`echo $i | gawk '{gsub("###"," ",$0);print $0}'`
>    grep -in $key "$f" | gawk -v var="$f" '{print var":"$0}'
>    done

Is that any different from "grep -inr $1 $2", apart from being slower?

-- 
Bj�rn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Don't use the "use" clause

[adaworks]

"Anonymous Coward" <spam@spam.com> wrote in message
news:slrndnv9qv.1r7.bogus_addy@tango.mindfuq.org...
>
> I agree.  I personally take it an extreme step further, and never use
> use clauses anywhere.  They shouldn't even be in the language.  Every
> Ada project I've worked on that had a coding standard banned the use
> clause, and rightly so.
>
Three features of the language, all useful at times, are the visibility clause
(use) and the renames option, and the goto.  Even though all are
potentially problematic, they are also useful at times.

The visibilty clause is most problematic when used at the global level.  The
renames creates problems when it is used across library units.   The goto
sometimes becomes the only good choice for a rare number of circumstances.

Someone, I forget who, once said that "People who make up strict rules
for programmers tend to be people who no longer write production programs -
or never did."   While this probably does not apply to you, it does seem to
fit a lot of people who invent coding standards.

I knew one programming manager who disallowed declare blocks because
he felt they led to too much ad hoc design.  That is, programmers could make
up for design inadequacies by inserting declare blocks.  A few people in our
community object to nesting subprograms in the declarative part of another
subprogram.  "Promote it to a package specification," they demand.   Still
others point out that enumeration types are an artifact of an old-fashioned
style of programming.  They are non-extensible and create visibility problems.

We could go on.  Each reader will have some favorite part of the language
that should be banned.   My own least favorite feature, now that we have
inheritance, is variant records.

Visibility is one of the most least understood concepts in Ada.   It drives new
Ada programmers nuts.  Experience Ada programmers learn to appreciate
its power and find it useful.  The also know when visibility clauses are
appropriate and when they are not.   This is not, as someone else mentioned,
simply a matter of taste.  It is not just a matter of style.

Ada provides a lot of options for relaxing the default strictness of many
constructs.
This has value in different programming environments.   The C family of
languages
has many constructs that default to unsafe.  Ada, for most constructs, defaults
to
safe.  Being able to relax this default often opens the door to Ada for people
who
are not creating safety-critical software.   For example, I don't need to worry
about
visibility very much when writing scientific programs.

In industrial engineering there is a principle that has to do with 100% checking
for
0.001% probable error.   Standards need to be adopted that are appropriate to
the context in which we are working. In a sloppy environment such as Microsoft
Windows,
is it useful to avoid the use clause when we already know we are working in an
error-prone environment?

Richard Riehle

Re: Don't use the "use" clause

[Jeffrey R. Carter]

adaworks@sbcglobal.net wrote:

> "Anonymous Coward" <spam@spam.com> wrote in message
> news:slrndnv9qv.1r7.bogus_addy@tango.mindfuq.org...
> 
>>I agree.  I personally take it an extreme step further, and never use
>>use clauses anywhere.  They shouldn't even be in the language.  Every
>>Ada project I've worked on that had a coding standard banned the use
>>clause, and rightly so.
> 
> Three features of the language, all useful at times, are the visibility clause
> (use) and the renames option, and the goto.  Even though all are
> potentially problematic, they are also useful at times.

Right. The OP might want to use SPARK, which does not have use clauses.

> Visibility is one of the most least understood concepts in Ada.   It drives new
> Ada programmers nuts.  Experience Ada programmers learn to appreciate
> its power and find it useful.  The also know when visibility clauses are
> appropriate and when they are not.   This is not, as someone else mentioned,
> simply a matter of taste.  It is not just a matter of style.

There's also a question of judgment. The packages in the core language 
definition and the standard library (Ada.*) should be familiar to anyone reading 
Ada code; using these packages should not impact readability. A project may have 
a its own standard library in addition to these, that should be familiar to 
anyone working on the project, and a similar argument applies to these. A 
package used in a single subsystem of a large project is a different creature 
and is probably not a good candidate for use.

-- 
Jeff Carter
"Your mother was a hamster and your father smelt of elderberries."
Monty Python & the Holy Grail
06

Re: Don't use the "use" clause

[Stephen Leake]

"Jeffrey R. Carter" <spam@spam.com> writes:

>>>I agree.  I personally take it an extreme step further, and never use
>>>use clauses anywhere.  They shouldn't even be in the language.  Every
>>>Ada project I've worked on that had a coding standard banned the use
>>>clause, and rightly so.

Hmph. _My_ coding standard doesn't say that.

It says "no use clauses in package specs. Use clauses in bodies must
be localized as much as possible, and should be used whenever the
package name is present in several statements within a declarative
region". 

That preserves very clear references in package specs, where they are
most important, preserves fairly clear references in package bodies,
and improves readability of subprograms. As it should be :).

>> Three features of the language, all useful at times, are the
>> visibility clause (use) and the renames option, and the goto. Even
>> though all are potentially problematic, they are also useful at
>> times.
>
> Right. The OP might want to use SPARK, which does not have use clauses.

That seems odd. What does SPARK gain by outlawing use clauses? Surely
the examiner can handle the extra name resolution!

>> Visibility is one of the most least understood concepts in Ada. It
>> drives new Ada programmers nuts. 

That has not been my experience. Perhaps my coding standard is enough
to prevent that, or perhaps the GNAT error messages are good enough.

>> Experience Ada programmers learn to appreciate its power and find
>> it useful. 

yes.

>> The also know when visibility clauses are appropriate and when they
>> are not. This is not, as someone else mentioned, simply a matter of
>> taste. It is not just a matter of style.
>
> There's also a question of judgment. The packages in the core language
> definition and the standard library (Ada.*) should be familiar to
> anyone reading Ada code; using these packages should not impact
> readability. A project may have a its own standard library in addition
> to these, that should be familiar to anyone working on the project,
> and a similar argument applies to these. A package used in a single
> subsystem of a large project is a different creature and is probably
> not a good candidate for use.

It's not a question of "familiarity". I'm totally familiar with the
code I wrote today, but next year I won't be. 

It's a question of balance between distance from the full package
name, and readability.

-- 
-- Stephe

Re: Don't use the "use" clause

[Ed Falis]

On Mon, 23 Jan 2006 21:27:19 -0500, Stephen Leake <stephen_leake@acm.org>  
wrote:

> It's a question of balance between distance from the full package
> name, and readability.

You 'da man!

- Ed

Re: Don't use the "use" clause

[Jeffrey R. Carter]

Stephen Leake wrote:

> It's not a question of "familiarity". I'm totally familiar with the
> code I wrote today, but next year I won't be. 

It's not a question of what you're familiar with; it's a question of what you 
can reasonably expect all readers (including yourself in a year) to be familiar 
with.

-- 
Jeff Carter
"Your mother was a hamster and your father smelt of elderberries."
Monty Python & the Holy Grail
06

Re: Don't use the "use" clause

[Stephen Leake]

"Jeffrey R. Carter" <spam@spam.com> writes:

> Stephen Leake wrote:
>
>> It's not a question of "familiarity". I'm totally familiar with the
>> code I wrote today, but next year I won't be.
>
> It's not a question of what you're familiar with; it's a question of
> what you can reasonably expect all readers (including yourself in a
> year) to be familiar with.

Which is exactly nothing; that's my point. 

Not even Ada.Text_IO. I don't use that much any more; there are other
packages I use far more often. I know "Put" and "Get"; anything else I
usually have to look up.

-- 
-- Stephe

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Mon, 23 Jan 2006 21:27:19 -0500, Stephen Leake wrote:

> It says "no use clauses in package specs.

Which implies that child and nested packages should be forbidden...

As well as all others, after all Standard is "use"-d. Why? It should not...

Hmm, where Standard is declared? Isn't *that* package "use"-d? (:-))

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Martin Dowie]

Dmitry A. Kazakov wrote:
> On Mon, 23 Jan 2006 21:27:19 -0500, Stephen Leake wrote:
>
>> It says "no use clauses in package specs.
>
> Which implies that child and nested packages should be forbidden...
>
> As well as all others, after all Standard is "use"-d. Why? It should
> not...
>
> Hmm, where Standard is declared? Isn't *that* package "use"-d? (:-))

No it isn't - all Ada programs are conceptually declared _within_ package
Standard : so no need to with or use it (see LRM A.1 54).

Cheers

-- Martin

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Tue, 24 Jan 2006 09:48:12 -0000, Martin Dowie wrote:

> Dmitry A. Kazakov wrote:
>> On Mon, 23 Jan 2006 21:27:19 -0500, Stephen Leake wrote:
>>
>>> It says "no use clauses in package specs.
>>
>> Which implies that child and nested packages should be forbidden...
>>
>> As well as all others, after all Standard is "use"-d. Why? It should
>> not...
>>
>> Hmm, where Standard is declared? Isn't *that* package "use"-d? (:-))
> 
> No it isn't - all Ada programs are conceptually declared _within_ package
> Standard : so no need to with or use it (see LRM A.1 54).

But Standard cannot be declared within itself, even conceptually! (:-))
Anyway nested declarations are equivalent to "use"-ing.

I must admit, that I never managed to understand the point of use-haters.
(Probably because they don't have any (:-)) The packages comprise a tree.
With "use"-ing it is levered to a DAG. I would *really* like to be able to
do it without "use" as well, i.e. to have children of multiple parents. But
that's aside. Is the point that all nodes along any path need to be
mentioned? If so, then "use" or not is quite irrelevant. If not then what?
To keep it a tree, then "with" must be outlawed as well. I don't get it.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[brian.b.mcguinness]

I do not have a lot of experience with Ada.  I am working on a time and
date package that
uses routines from standard Ada packages.  At first I tried writing the
code without any "use" clauses but I kept running into problems so I
finally gave up in frustration and "used" all of the standard packages
I "with"ed.  I suspect that many other people have the same experience.

Frankly, I see no reason to avoid "use".  The whole point of providing
overloading is so that you can have several functions or procedures
with the same name.  And I am perfectly happy to ignore any coding
guideline that results in endless frustration without serving any
useful purpose.

--- Brian

Re: Don't use the "use" clause

[Simon Wright]

brian.b.mcguinness@lmco.com writes:

> I do not have a lot of experience with Ada.  I am working on a time
> and date package that uses routines from standard Ada packages.  At
> first I tried writing the code without any "use" clauses but I kept
> running into problems so I finally gave up in frustration and "used"
> all of the standard packages I "with"ed.  I suspect that many other
> people have the same experience.
>
> Frankly, I see no reason to avoid "use".  The whole point of
> providing overloading is so that you can have several functions or
> procedures with the same name.  And I am perfectly happy to ignore
> any coding guideline that results in endless frustration without
> serving any useful purpose.

Well, I suppose it depends on the environment you're working in. If
the result of that approach is that the code you've worked on gets
binned so that it can be done again 'properly' (ie, according to the
codes of practice appropriate to the SIL rating of the project) then
you might as well have stayed at home.

You may be like many engineers dumped into a project needing Ada
experience but without the proper training, in which case my
sympathies.

I had fun with an Ada DBMS that was written in '83 with 'use'; the
only way to make sense of it under '95 was to remove all the use
clauses. Most compilers are going to have trouble browsing to the
correct overloaded subprogram if the code doesn't compile.

That said, I've just looked at some of my own code and there is a fair
sprinkling of 'use' -- mainly for Ada.Text_IO and
internally-instantiated generic container packages. About 80 lines out
of 10_000.

--S

Re: Don't use the "use" clause

[Stephen Leake]

brian.b.mcguinness@lmco.com writes:

> I do not have a lot of experience with Ada.  I am working on a time and
> date package that
> uses routines from standard Ada packages.  At first I tried writing the
> code without any "use" clauses but I kept running into problems 

Next time, bring those "problems" here, or to your mentor; there are
better ways of solving them.

What compiler are you using? GNAT usually gives excellent error
messages in cases like this.

> so I finally gave up in frustration and "used" all of the standard
> packages I "with"ed.

Try adding the use clauses one at a time, in the smallest declaration
region you can (in the subprograms, not the package).

> I suspect that many other people have the same experience.

Yes, that's true.

Going overboard with "use" means you don't learn what each package has
in it. That's an important part of understanding a program.

> Frankly, I see no reason to avoid "use".  The whole point of providing
> overloading is so that you can have several functions or procedures
> with the same name.  

Yes. "use type" provides that for operators; most coding standards
that forbid "use" permit "use type". But I agree that overloading,
when used properly, increases the readability of the program.

> And I am perfectly happy to ignore any coding guideline that results
> in endless frustration without serving any useful purpose.

That is not acceptable, if you have agreed to join a project that uses
that particular coding standard. Instead, you must work to educate the
people on the project, and get the coding standard changed.

-- 
-- Stephe

Re: Don't use the "use" clause

[Jeffrey R. Carter]

Stephen Leake wrote:

> brian.b.mcguinness@lmco.com writes:
> 
>>I do not have a lot of experience with Ada.  I am working on a time and
>>date package that
>>uses routines from standard Ada packages.  At first I tried writing the
>>code without any "use" clauses but I kept running into problems 
> 
> Next time, bring those "problems" here, or to your mentor; there are
> better ways of solving them.

It would probably be a good experience for the OP to work out how to get the 
code working without use clauses. That would increase his understanding of Ada 
and visibility a great deal.

-- 
Jeff Carter
"My mind is aglow with whirling, transient nodes of
thought, careening through a cosmic vapor of invention."
Blazing Saddles
85

Re: Don't use the "use" clause

[Randy Brukardt]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
news:1wq3tkzfwt0bw.1ad4zqlgln451$.dlg@40tude.net...
...
> But Standard cannot be declared within itself, even conceptually! (:-))
> Anyway nested declarations are equivalent to "use"-ing.

Not really, direct visibility is a hiding relationship (new items hide old
ones); use is a canceling relationship.

> I must admit, that I never managed to understand the point of use-haters.
> (Probably because they don't have any (:-)) The packages comprise a tree.
> With "use"-ing it is levered to a DAG. I would *really* like to be able to
> do it without "use" as well, i.e. to have children of multiple parents.
But
> that's aside. Is the point that all nodes along any path need to be
> mentioned? If so, then "use" or not is quite irrelevant. If not then what?
> To keep it a tree, then "with" must be outlawed as well. I don't get it.

For me at least, it is about being able to find declarations sensibly -
without having to rely on fancy tools which necessarily require the code to
be complete and compilable. Thus, strict limits on use clauses. Moreover,
nested (direct) visibility is for the birds, in all of its forms. I want
(and write) prefixes on *all* non-local declarations (with the exception of
operators, which I consider a property more than a separate entity). That
means that I do generally write Parent.operation for things declared in the
parent of a child package. I hate it that the compiler will not allow me to
enforce this.

Does this mean that I don't want child packages? Not at all; child packages
are about extending the parent package. They give access to the entities of
the private part that are otherwise not visibility in any way. I don't want
any direct visibility on the parent, and think it is a mistake that it is
there (it causes various anomolies that we've spent a lot of work
eliminating from packages with just context clause relationships). Indeed, I
probably would have modeled the child unit as a special kind of context
clause, rather than using nesting.

Remember the difference between "visibility" (the ability to use an entities
name) and "direct visibility" (the ability to an entities name without
qualification). I want the former (of course), and only want the latter for
local declarations.

Summary: "visibility" == good; "direct visibility" == bad (well, at least if
not strictly limited).

                             Randy.

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Tue, 24 Jan 2006 17:38:12 -0600, Randy Brukardt wrote:

> "Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
> news:1wq3tkzfwt0bw.1ad4zqlgln451$.dlg@40tude.net...
> ...
>> But Standard cannot be declared within itself, even conceptually! (:-))
>> Anyway nested declarations are equivalent to "use"-ing.
> 
> Not really, direct visibility is a hiding relationship (new items hide old
> ones); use is a canceling relationship.

Well, let's consider a better (IMO) design, which would make "use" illegal
when it would cause any name conflict. The question is: will such
"safe-use" be OK?

>> I must admit, that I never managed to understand the point of use-haters.
>> (Probably because they don't have any (:-)) The packages comprise a tree.
>> With "use"-ing it is levered to a DAG. I would *really* like to be able to
>> do it without "use" as well, i.e. to have children of multiple parents. But
>> that's aside. Is the point that all nodes along any path need to be
>> mentioned? If so, then "use" or not is quite irrelevant. If not then what?
>> To keep it a tree, then "with" must be outlawed as well. I don't get it.
> 
> For me at least, it is about being able to find declarations sensibly -
> without having to rely on fancy tools which necessarily require the code to
> be complete and compilable.

I agree with this.

> Thus, strict limits on use clauses. Moreover,
> nested (direct) visibility is for the birds, in all of its forms. I want
> (and write) prefixes on *all* non-local declarations (with the exception of
> operators, which I consider a property more than a separate entity). That
> means that I do generally write Parent.operation for things declared in the
> parent of a child package. I hate it that the compiler will not allow me to
> enforce this.

Then you should answer the question above as no. Then also it is no matter
whether "use" hides anything. In my view it matters.

> Does this mean that I don't want child packages? Not at all; child packages
> are about extending the parent package. They give access to the entities of
> the private part that are otherwise not visibility in any way. I don't want
> any direct visibility on the parent, and think it is a mistake that it is
> there (it causes various anomolies that we've spent a lot of work
> eliminating from packages with just context clause relationships). Indeed, I
> probably would have modeled the child unit as a special kind of context
> clause, rather than using nesting.

I fully agree with this.

> Remember the difference between "visibility" (the ability to use an entities
> name) and "direct visibility" (the ability to an entities name without
> qualification). I want the former (of course), and only want the latter for
> local declarations.
> 
> Summary: "visibility" == good; "direct visibility" == bad (well, at least if
> not strictly limited).

No. Both are bad because they couple things. I think that access should not
be equivalent to visibility, either direct or indirect.

As for visibility, ideally, there should be only direct one, provided that
the language would ensure consistency of all views and that it would have
tools to control it. For example,

- transitive "use",
- an ability to "use" things visible to another package,
- to merge declaration areas of several packages,
- to export the declaration area of a nested package (especially of an
instantiated generic package)
- proper renaming of objects.
- proper renaming of types,
- tools to prevent naming space contamination by generics.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Randy Brukardt]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
news:jhy2wes1y8jp$.17t7iu2n10zu1$.dlg@40tude.net...
> On Tue, 24 Jan 2006 17:38:12 -0600, Randy Brukardt wrote:
...
> > Summary: "visibility" == good; "direct visibility" == bad (well, at
least if
> > not strictly limited).
>
> No. Both are bad because they couple things. I think that access should
not
> be equivalent to visibility, either direct or indirect.

I was speaking formally here. I think you're still confused about have
"visibility" means in Ada, because something being visible means no more and
no less than that it can be accessed by name (and how else can you access
something?). Perhaps it would be better to talk about "potential visibility"
or something like that.

When something is visible, all that means is that you can write its name
(somehow) and possibly access the entity. Usually that somehow is through
selected notation. If something is not visible, then you can't write its
name in any way at all, including selected notation.

With clauses are all about access by name. In the few cases where Ada allows
access to something without using its name, the access is essentially always
allowed -- it is not tied to visibility at all. (Think dispatching, types,
etc.)

> As for visibility, ideally, there should be only direct one, provided that
> the language would ensure consistency of all views and that it would have
> tools to control it.

You want to get rid of selected notation? So that there is no way to figure
out where rarely used things are declared? An occurrence of "Blocked_Sum" in
a program can be totally mysterious, while Message_Statistics.Blocked_Sum is
much clearer. Thanks, but no thanks.

                         Randy.

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Wed, 25 Jan 2006 15:46:06 -0600, Randy Brukardt wrote:

> "Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
> news:jhy2wes1y8jp$.17t7iu2n10zu1$.dlg@40tude.net...
>> On Tue, 24 Jan 2006 17:38:12 -0600, Randy Brukardt wrote:
> ...
>>> Summary: "visibility" == good; "direct visibility" == bad (well, at least if
>>> not strictly limited).
>>
>> No. Both are bad because they couple things. I think that access should not
>> be equivalent to visibility, either direct or indirect.
> 
> I was speaking formally here. I think you're still confused about have
> "visibility" means in Ada, because something being visible means no more and
> no less than that it can be accessed by name (and how else can you access
> something?).

Name (identifier) is not the only way to access an object. Visibility
(common sense) is about access to names. The access to the indicated object
(full view, partial view etc) is another story.

Anyway, differentiating between direct and indirect visibility introduces
aliasing, which is not a good thing. OK, you might say that eluding "use"
would prevent aliasing, but then that argument would hit child and nested
packages as well.

> Perhaps it would be better to talk about "potential visibility"
> or something like that.
> 
> When something is visible, all that means is that you can write its name
> (somehow) and possibly access the entity. Usually that somehow is through
> selected notation. If something is not visible, then you can't write its
> name in any way at all, including selected notation.

Exactly, see above.

>> As for visibility, ideally, there should be only direct one, provided that
>> the language would ensure consistency of all views and that it would have
>> tools to control it.
> 
> You want to get rid of selected notation?

Ideally "." should be an operation as any other, to override and to
overload.

> So that there is no way to figure
> out where rarely used things are declared? An occurrence of "Blocked_Sum" in
> a program can be totally mysterious, while Message_Statistics.Blocked_Sum is
> much clearer.

Why is it cleaner? It could only be if Message_Statistics were better known
than Blocked_Sum. That is a result of design, not a function of nesting or
other hierarchy. Example: I know well that "*" can multiply string by
number, but I cannot say where it is declared without searching through
ARM.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Randy Brukardt]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
news:92132rehnlw6$.127gl4b6mfbnx.dlg@40tude.net...
> On Wed, 25 Jan 2006 15:46:06 -0600, Randy Brukardt wrote:
...
> Anyway, differentiating between direct and indirect visibility introduces
> aliasing, which is not a good thing. OK, you might say that eluding "use"
> would prevent aliasing, but then that argument would hit child and nested
> packages as well.

It does. I think all packages should have the same sort of indirect
visibility; I'd ban nested ones, and child ones would work the same as other
library units. But that's not Ada.

For Ada, avoiding child units just isn't possible, unless you want to build
giant monolithic packages. So I have to take the bad visibility with the
good extension and hiding features. Use clauses have no such good
features -- they only have bad visibility.

I'm afraid I didn't really realize how much of a problem visibility on the
parent of a child unit is until we were working on limited with and private
with. At lot of the anomolies only happened because of parent units. Of
course, that was about 8 years too late for Ada...

>> You want to get rid of selected notation?

>Ideally "." should be an operation as any other, to override and to
>overload.

There has to be some basement in the syntax of operations/operators that
never change. Otherwise, you end up with a write-only language. The
visibility use of "." is one of those (obviously, you could use a different
symbol than ".", but I think you need something whose meaning doesn't change
for this purpose). Dereferencing is another matter, and it's unfortunate
that Ada mixes the two up -- they're completely unrelated. Pascal's "^"
operator would be better (and I agree that that should be overridable).

...
> > So that there is no way to figure
> > out where rarely used things are declared? An occurrence of
"Blocked_Sum" in
> > a program can be totally mysterious, while
Message_Statistics.Blocked_Sum is
> > much clearer.
>
> Why is it cleaner? It could only be if Message_Statistics were better
known
> than Blocked_Sum. That is a result of design, not a function of nesting or
> other hierarchy.

Packages are the root of all organization in Ada; it's only the packages
that you have to know instantly to understand an Ada program with few use
clauses. Having to know all of the entities in a program well to understand
it is going to be information overload.

> Example: I know well that "*" can multiply string by
> number, but I cannot say where it is declared without searching through
> ARM.

"*" is a terrible name for a string operation, and (while I know it's there)
it's not one that I'd ever think of. (It's certainly not a native operation
of strings, and thus shouldn't be named with an operator. "*" is only for
numbers and numerical abstractions.) In any case, I would write it as
Ada.Strings.Unbounded."*" -- and then I'd know instantly that it is a string
operation, and know where to look if I need to know more.

I think you'd have a better argument if the routine was called
"Replicate_String". But that was a previous point (I forget who said it) --
the name of this operation should just be "Replicate", and the package name
or object name will tell you want is getting "Replicated". (That's the
naming we used in Claw, for instance, very short names for only the
operation, where either the object name or the package name tell you what
the type is. If you use use clauses and call all of your windows W, your
Claw program will be indecipherable. Tough, use better names.)

Note that the prefixed call notation (introduced in Ada 2005) reduces the
need for use clauses and traditional selected notation by using the object
name instead. That maps very well to both the Claw naming and an otherwise
use-free environment -- it should reduce the clutter in programs of people
that don't use use clauses and increase the readability for those that do
(by emphisizing the object, and thus the type, of the operation). A win-win
situation...


                               Randy.

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Thu, 26 Jan 2006 19:04:38 -0600, Randy Brukardt wrote:

> "Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
> news:92132rehnlw6$.127gl4b6mfbnx.dlg@40tude.net...
>> On Wed, 25 Jan 2006 15:46:06 -0600, Randy Brukardt wrote:
> ...
>> Anyway, differentiating between direct and indirect visibility introduces
>> aliasing, which is not a good thing. OK, you might say that eluding "use"
>> would prevent aliasing, but then that argument would hit child and nested
>> packages as well.
> 
> It does. I think all packages should have the same sort of indirect
> visibility; I'd ban nested ones, and child ones would work the same as other
> library units. But that's not Ada.

OK, without generics it might work.

>>> You want to get rid of selected notation?
> 
>>Ideally "." should be an operation as any other, to override and to
>>overload.
> 
> There has to be some basement in the syntax of operations/operators that
> never change.

It should be up to the programmer. The language should not prescribe the
meaning of "*" or ".". However it can forbid overriding "." for certain
things, like packages.

> Otherwise, you end up with a write-only language. The
> visibility use of "." is one of those (obviously, you could use a different
> symbol than ".", but I think you need something whose meaning doesn't change
> for this purpose). Dereferencing is another matter, and it's unfortunate
> that Ada mixes the two up -- they're completely unrelated. Pascal's "^"
> operator would be better (and I agree that that should be overridable).

Well, I don't think that there should be such operator at all. Reference
types should inherit parent's operations, which in effect would mean their
full transparency. If ":=" should mean reference copy, then the reference
type have to override it.

>>> So that there is no way to figure
>>> out where rarely used things are declared? An occurrence of "Blocked_Sum" in
>>> a program can be totally mysterious, while Message_Statistics.Blocked_Sum is
>>> much clearer.
>>
>> Why is it cleaner? It could only be if Message_Statistics were better known
>> than Blocked_Sum. That is a result of design, not a function of nesting or
>> other hierarchy.
> 
> Packages are the root of all organization in Ada; it's only the packages
> that you have to know instantly to understand an Ada program with few use
> clauses. Having to know all of the entities in a program well to understand
> it is going to be information overload.

Packages have no properties of their own. Programs are written in terms of
types, objects, operations.

>> Example: I know well that "*" can multiply string by
>> number, but I cannot say where it is declared without searching through
>> ARM.
> 
> "*" is a terrible name for a string operation, and (while I know it's there)
> it's not one that I'd ever think of. (It's certainly not a native operation
> of strings, and thus shouldn't be named with an operator. "*" is only for
> numbers and numerical abstractions.) In any case, I would write it as
> Ada.Strings.Unbounded."*" -- and then I'd know instantly that it is a string
> operation, and know where to look if I need to know more.

But it is not a string operation. It is a string-valued operation defined
on strings and numbers. Ada.Strings.Unbounded."*" is misleading. It could
be in Ada.Numeric or in Ada.Container. Actually, it is a reincarnation of
Hungarian notation for subroutines - an evil thing. Names should reflect
semantics, rather than types.

> I think you'd have a better argument if the routine was called
> "Replicate_String".

Take Is_Letter.

> But that was a previous point (I forget who said it) --
> the name of this operation should just be "Replicate", and the package name
> or object name will tell you want is getting "Replicated". (That's the
> naming we used in Claw, for instance, very short names for only the
> operation, where either the object name or the package name tell you what
> the type is. If you use use clauses and call all of your windows W, your
> Claw program will be indecipherable. Tough, use better names.)

This is a no-use-friendly naming convention, especially useful for
generics. But that does not mean that there cannot be a use-friendly
alternative.

> Note that the prefixed call notation (introduced in Ada 2005) reduces the
> need for use clauses and traditional selected notation by using the object
> name instead.

Firstly, I think that introduction of prefixed notation probably was a
mistake. We'd better have removed it for tasks and protected objects.

Secondly, prefix notation as introduced in Ada 2005 is an equivalent of use
clause! In C++ both "use-" and "with-like-prefix" notations coexist. For
example:

   X.A::B::C::D::Foo (); // "with-like-prefix"
   X.Foo ();	   // "use-like-prefix"

Ada's equivalent of the first could be:

   X.Standard.A.B.C.D.Foo; -- Let's enjoy fully qualified names!

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Georg Bauhaus]

On Fri, 2006-01-27 at 16:23 +0100, Dmitry A. Kazakov wrote:

> > Packages are the root of all organization in Ada; it's only the packages
> > that you have to know instantly to understand an Ada program with few use
> > clauses. Having to know all of the entities in a program well to understand
> > it is going to be information overload.
> 
> Packages have no properties of their own. Programs are written in terms of
> types, objects, operations.

I think "written" is the word that hints to a meaning of
packages in Ada program text, less so to executable programs after
compilation. And for sure, when writing, you can think about module
properties, and how to map these to ADTs or ASMs. You organize.
If a package is an ASM, then you could (if not in Ada) express
the state of the ASM between operation as an invariant, to be
a property of the package.

(Even when compiled, I'm not sure that packages will not exhibit
properties during elaboration at run time.)

-- Georg 

Re: Don't use the "use" clause

[Randy Brukardt]

"Georg Bauhaus" <bauhaus@futureapps.de> wrote in message
news:1138379742.13763.9.camel@sonnenregen...
> On Fri, 2006-01-27 at 16:23 +0100, Dmitry A. Kazakov wrote:
>
> > > Packages are the root of all organization in Ada; it's only the
packages
> > > that you have to know instantly to understand an Ada program with few
use
> > > clauses. Having to know all of the entities in a program well to
understand
> > > it is going to be information overload.
> >
> > Packages have no properties of their own. Programs are written in terms
of
> > types, objects, operations.
>
> I think "written" is the word that hints to a meaning of
> packages in Ada program text, less so to executable programs after
> compilation. And for sure, when writing, you can think about module
> properties, and how to map these to ADTs or ASMs. You organize.
> If a package is an ASM, then you could (if not in Ada) express
> the state of the ASM between operation as an invariant, to be
> a property of the package.
>
> (Even when compiled, I'm not sure that packages will not exhibit
> properties during elaboration at run time.)

Exactly. The meaning of a package is in it's organization and in its name.
These aren't things that have meaning to the compiler, they have meaning to
the reader. If they don't have meaning to the reader, then the system is
poorly defined (and the program would be better off with no package at all).

Packages in this sense are much like comments, other than that the compiler
checks that they are used consistently. There's never a *requirement* to use
a package, but a well-designed system is make up of packages (groupings) of
entities, not single entities floating around unorganized.

                           Randy.


                      Randy.

Re: Don't use the "use" clause

[Randy Brukardt]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
news:kzwbjdb0auzq.1kah1latt0mb1.dlg@40tude.net...
...
> Secondly, prefix notation as introduced in Ada 2005 is an equivalent of
use
> clause!

More of a replacement for the use clause. It has some use-like properties
for the subprogram name, but the object name is handled by normal visibility
rules. It would of course have fully qualified names.

But fully qualified names don't work for OOP in Ada, because it is extremely
difficult to tell where a particular operation is declared. Most of the
operations are inherited, after all, so the place where it is declared (and
thus the place that you use a fully qualified name to) is not the place
where the operation actually exists in the source code. That means that the
fully qualified name suggests that you look in the *wrong* place, and that
isn't helping anything.

OTOH, throwing in a pile of use clauses makes all kinds of unrelated stuff
visible. Prefixed notation only makes particular subprograms visible. In
that sense, it is like use type.

                            Randy.

Re: Don't use the "use" clause

[Dmitry A. Kazakov]

On Fri, 27 Jan 2006 17:18:06 -0600, Randy Brukardt wrote:

> "Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> wrote in message
> news:kzwbjdb0auzq.1kah1latt0mb1.dlg@40tude.net...
> ...
>> Secondly, prefix notation as introduced in Ada 2005 is an equivalent of use
>> clause!
> 
> More of a replacement for the use clause. It has some use-like properties
> for the subprogram name, but the object name is handled by normal visibility
> rules. It would of course have fully qualified names.
> 
> But fully qualified names don't work for OOP in Ada, because it is extremely
> difficult to tell where a particular operation is declared. Most of the
> operations are inherited, after all, so the place where it is declared (and
> thus the place that you use a fully qualified name to) is not the place
> where the operation actually exists in the source code. That means that the
> fully qualified name suggests that you look in the *wrong* place, and that
> isn't helping anything.

It is also so in general for OOP and advanced ADT. The declaration place
has no specific sense. Therefore fully qualified names is just noise. What
matters to the reader is not arbitrary declaration places, but
relationships between objects, types and operations. This is why prefix
notation is so beloved, though misleading with multiple parameters. "Use
type" also goes in this direction. [ Taken to extreme many OOPLs view
operations as if they were " members." ]
 
> OTOH, throwing in a pile of use clauses makes all kinds of unrelated stuff
> visible. Prefixed notation only makes particular subprograms visible. In
> that sense, it is like use type.

Yes, and as I said before, what is actually needed, is an ability of better
user-control over partial [direct] visibility, additionally to hard-wired
"use type." An obvious candidate for this is package. In Ada 83 it was
quite common to create proxy packages consisting solely of renamings. IMO
Ada needs a more elaborated stuff like this, provided that renaming would
finally fixed. The hierarchies of "implementation" packages and
"user-interface" packages aren't always same. Moreover, depending on
concrete use there could be more than one set of "interface" packages for
the same implementation.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Don't use the "use" clause

[Stephen Leake]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> writes:

> On Mon, 23 Jan 2006 21:27:19 -0500, Stephen Leake wrote:
>
>> It says "no use clauses in package specs.
>
> Which implies that child and nested packages should be forbidden...

Say what? Why do you need a use clause for a child or nested package?

Ah. You are saying that in terms of visibility, a child package has
the equivalent of a use clause for the parent. That's true. And the
parent name is right there at the top of the file.

I don't see the "no use clause" fanatics also saying "no child packages".

-- 
-- Stephe

Re: Don't use the "use" clause

[Martin Dowie]

Stephen Leake wrote:
>> Right. The OP might want to use SPARK, which does not have use
>> clauses.
>
> That seems odd. What does SPARK gain by outlawing use clauses? Surely
> the examiner can handle the extra name resolution!

But the human reader can't handle the extra name resolution! :-)

Cheers

-- Martin

Re: Don't use the "use" clause

[Stephen Leake]

"Martin Dowie" <martin.dowie@baesystems.com> writes:

> Stephen Leake wrote:
>>> Right. The OP might want to use SPARK, which does not have use
>>> clauses.
>>
>> That seems odd. What does SPARK gain by outlawing use clauses? Surely
>> the examiner can handle the extra name resolution!
>
> But the human reader can't handle the extra name resolution! :-)

Well, _I_ can :). Most times, I think I'm human :).

-- 
-- Stephe

Re: Don't use the "use" clause

[Martin Dowie]

>>> That seems odd. What does SPARK gain by outlawing use clauses?
>>> Surely the examiner can handle the extra name resolution!
>>
>> But the human reader can't handle the extra name resolution! :-)
>
> Well, _I_ can :). Most times, I think I'm human :).

Yeah, but if you're using SPARK, your probably not interested in just /most/
times... ;-)

Cheers

-- Martin

Re: Don't use the "use" clause

[Peter Amey]

Martin Dowie wrote:
> Stephen Leake wrote:
> 
>>>Right. The OP might want to use SPARK, which does not have use
>>>clauses.
>>
>>That seems odd. What does SPARK gain by outlawing use clauses? Surely
>>the examiner can handle the extra name resolution!
> 
> 
> But the human reader can't handle the extra name resolution! :-)
> 

I haven't followed all of this thread but do wonder if poor initial name 
choice is sometimes a driver for the desire to employ "use"?  I think 
the original topic was Ada Quality and Style so naming may be on topic 
anyway.

I think the trick is to choose names knowing that they will be read in 
sequences separated by dots.  Then the desire to strip away chunks of 
the name becomes less pressing.

I often see (ghastly) things like:

Engine_Sensor_Class.Engine_Speed_Sensors.Turbine_Speed.Read_Turbine_Speed

no wonder people want to employ use clauses to shorten it!

If instead we had:

Sensors.Speed.Turbine.Get

then a use clause is less useful and might even be positively misleading.

A side benefit of banning "use" (but not "use type") which we do in 
SPARK, is it encourages this kind of naming because nobody ever has to 
worry about what a name might look like with bits of it missing.

Peter

Re: Don't use the "use" clause

[Martin Dowie]

Peter Amey wrote:
> I haven't followed all of this thread but do wonder if poor initial name 
> choice is sometimes a driver for the desire to employ "use"?  I think 
> the original topic was Ada Quality and Style so naming may be on topic 
> anyway.
> 
> I think the trick is to choose names knowing that they will be read in 
> sequences separated by dots.  Then the desire to strip away chunks of 
> the name becomes less pressing.
> 
> I often see (ghastly) things like:
> 
> Engine_Sensor_Class.Engine_Speed_Sensors.Turbine_Speed.Read_Turbine_Speed

And I know where you see this! ;-)

Cheers

-- Martin

Re: Don't use the "use" clause

[Jeffrey R. Carter]

Peter Amey wrote:

> I often see (ghastly) things like:
> 
> Engine_Sensor_Class.Engine_Speed_Sensors.Turbine_Speed.Read_Turbine_Speed
> 
> no wonder people want to employ use clauses to shorten it!
> 
> If instead we had:
> 
> Sensors.Speed.Turbine.Get
> 
> then a use clause is less useful and might even be positively misleading.

The ability to choose names well, like the ability to create useful 
abstractions, seems to be limited to a small percentage of SW developers. When 
you're on a project and are given Engine_Sensor_Class.Engine_Speed_Sensors and 
the task of implementing the turbine speed sensor interface, it's hard to get 
things named Sensors.Speed.Turbine.Get. Even 
Engine_Sensor_Class.Engine_Speed_Sensors.Turbine.Get might meet with resistance.

I won't even get into the possibility that grouping all engine sensors together 
might be incidental packaging, and Engine.Turbine.Speed.Get might be a better 
approach. I've seen too many embedded projects where all the external interfaces 
were in one gigantic package.

-- 
Jeff Carter
"If I could find a sheriff who so offends the citizens of Rock
Ridge that his very appearance would drive them out of town ...
but where would I find such a man? Why am I asking you?"
Blazing Saddles
37

Re: Don't use the "use" clause

[Stephen Leake]

Peter Amey <peter.amey@praxis-cs.co.uk> writes:

> I haven't followed all of this thread but do wonder if poor initial
> name choice is sometimes a driver for the desire to employ "use"?  I
> think the original topic was Ada Quality and Style so naming may be on
> topic anyway.
>
> I think the trick is to choose names knowing that they will be read in
> sequences separated by dots.  Then the desire to strip away chunks of
> the name becomes less pressing.
>
> I often see (ghastly) things like:
>
> Engine_Sensor_Class.Engine_Speed_Sensors.Turbine_Speed.Read_Turbine_Speed
>
> no wonder people want to employ use clauses to shorten it!
>
> If instead we had:
>
> Sensors.Speed.Turbine.Get

True. But how about:

declare
    use Sensors.Speed.Turbine;
begin
    Get (Sensor_1);
    Compute (Sensor_1);
    Get (Sensor_2);
    Compute (Sensor_2);
end;

which is much more realistic.

The "no use" alternative:

    Sensors.Speed.Turbine.Get (Sensors.Speed.Turbine.Sensor_1);
    Sensors.Speed.Turbine.Compute (Sensors.Speed.Turbine.Sensor_1);
    Sensors.Speed.Turbine.Got (Sensors.Speed.Turbine.Sensor_2);
    Sensors.Speed.Turbine.Compute (Sensors.Speed.Turbine.Sensor_2);


Which is more readable? And which one has "Got" instead of "Get"?

-- 
-- Stephe

Re: Don't use the "use" clause

[Anonymous Coward]

In article <Ij4Bf.1960$2O6.514@newssvr12.news.prodigy.com>, 
<adaworks@sbcglobal.net> wrote:
> 
> Someone, I forget who, once said that "People who make up strict
> rules for programmers tend to be people who no longer write
> production programs - or never did."  While this probably does not
> apply to you, it does seem to fit a lot of people who invent coding
> standards.

I find that the strictest of coding standards is a great benefit to
the largest and least disciplined developement teams.  Excessive use
of the use clause (along with other sloppy programming practices like
excessive global variables) calls for restraints.  Your typical
variety of C programmers who learned the Ada syntax on the job and are
drawn to a Windows environment is the stereotype that comes to mind.
The shortcoming of strict rules is negligable compared to mess that it
prevents in this situation.

OTOH, disciplined, experienced Ada developers who don't abuse the
unruly and lenient constructs (use clause, gotos) can be more
productive without the restrictions.

The latter is a rare case.  I'm currently working in an environment
that has no restrictions, and most of the staff is quite disciplined
and knowledgable.  However there are a couple exceptions.  I have been
forced to write subprograms to export private types of some of my
packages as a public types, because the user of my package (who is new
to Ada) just wants a plain float, or an integer.

Re: Ada Quality and Style book discussion

[Simon Wright]

Anonymous Coward <spam@spam.com> writes:

> The project I worked on that banned "_Type" also tried to encourage
> developers to choose identifiers that make a complete grammatically
> correct english sentence, as if it were more important that
> non-technical folks could read the code than the maintainers.  
>
> It didn't work out too well, because when you make an english sentence
> in one usage, the same identifers make the code look like crap where
> an english sentence doesn't exist.  ie.
>
>    function compute_altitude (using : in temperature;
>                               and   : in dew_point;
>                               with  : in pressure) return altitude is
>    begin
>
>       return (using + and / with);
>
>    end compute_altitude;
>
> Obviously that's a bogus formula.. but it should be clear from this
> that making code read like english down to the point of including
> articles like "and", "with", "is", asks for disaster.  Some folks
> really complied with this direction, and wrote code like that function
> above - I'm not joking.

There's an interesting point here. It makes a lot of sense to me to
make subprogram parameter names as helpful as possible to the caller;
this includes naming them 'from the outside' without any regard as to
how clumsy things may seem from the inside.

One could always use renaming to name the parameters more conveniently
from the inside view, though it would have to be a pretty extreme case
to justify it I would have thought.

As an extreme case, we had a message sending procedure declared like

  procedure Send (Message_In : String; To_The_Stream : Stream);

because from the writer's point of view Message_In was indeed an input
to his procedure. Of course from the reader's side it makes no sense
at all.

Much better as

  procedure Send (The_Message : String; To_The_Stream : Stream);

or even (if the package name is suitably descriptive and there aren't
many other Sends in scope)

  procedure Send (S : String; To : Stream);

called as

  Send ("hello world!", To => Output);

Re: Ada Quality and Style book discussion

[Larry Kilgallen]

In article <m264qrhu52.fsf@grendel.local>, Simon Wright <simon@pushface.org> writes:

> One could always use renaming to name the parameters more conveniently
> from the inside view, though it would have to be a pretty extreme case
> to justify it I would have thought.

I have done something like renaming the XYZ parameter to Caller_XYZ
when there are lots of other XYZs floating around inside the subprogram.

Re: Ada Quality and Style book discussion

[Anonymous Coward]

In article <m264qrhu52.fsf@grendel.local>, Simon Wright wrote:
> 
> There's an interesting point here. It makes a lot of sense to me to
> make subprogram parameter names as helpful as possible to the
> caller; this includes naming them 'from the outside' without any
> regard as to how clumsy things may seem from the inside.
> 
> One could always use renaming to name the parameters more
> conveniently from the inside view, though it would have to be a
> pretty extreme case to justify it I would have thought.
> 
> As an extreme case, we had a message sending procedure declared like
> 
>   procedure Send (Message_In : String; To_The_Stream : Stream);
> 
> because from the writer's point of view Message_In was indeed an
> input to his procedure. Of course from the reader's side it makes no
> sense at all.
> 
> Much better as
> 
>   procedure Send (The_Message : String; To_The_Stream : Stream);
> 
> or even (if the package name is suitably descriptive and there aren't
> many other Sends in scope)
> 
>   procedure Send (S : String; To : Stream);
> 
> called as
> 
>   Send ("hello world!", To => Output);

Even better yet would be to avoid taking a position such that the
usage is only correct or readible from one perspective and not
another.  The excessive use of articles is at the core of problem in
your first example.  Here's how I might code it:

   procedure Send (Message : in String; Target : in Stream);

It's not clutsy from the inside or the outside, it's concise (with no
distracting articles), and it doesn't mislead.  It assumes the
audience/reader knows Ada.  If the reader doesn't know basic Ada, then
the problem is with the reader, not the code.

Re: Ada Quality and Style book discussion

[Simon Wright]

Anonymous Coward <spam@spam.com> writes:

> In article <m264qrhu52.fsf@grendel.local>, Simon Wright wrote:

>> As an extreme case, we had a message sending procedure declared like
>> 
>>   procedure Send (Message_In : String; To_The_Stream : Stream);
>> 
>> because from the writer's point of view Message_In was indeed an
>> input to his procedure. Of course from the reader's side it makes no
>> sense at all.

> Even better yet would be to avoid taking a position such that the
> usage is only correct or readible from one perspective and not
> another.  The excessive use of articles is at the core of problem in
> your first example.  Here's how I might code it:

Huh? The problem with my example was that the programmer had called
something Message_In because he was not thinking from the point of
view of the user of his package. I didn't have a real problem with
To_The_Stream, and I don't see why you do though personally I would
have just said To, as I indicated.

>    procedure Send (Message : in String; Target : in Stream);
>
> It's not clutsy from the inside or the outside, it's concise (with
> no distracting articles), and it doesn't mislead.  It assumes the
> audience/reader knows Ada.  If the reader doesn't know basic Ada,
> then the problem is with the reader, not the code.

I don't see what 'knowing Ada' has to do with it?

Re: Ada Quality and Style book discussion

[Anonymous Coward]

In article <m2br0gz2e3.fsf@grendel.local>, 
Simon Wright wrote:
> 
> Huh? The problem with my example was that the programmer had called
> something Message_In because he was not thinking from the point of
> view of the user of his package. 

I agree that the first example was problematic, and in part for the
same reason you do - because the author was thinking from his own
point of view rather than the user.  

But I'm saying remove the article "_In" and problem solved.  I'm not
saying the point of view should strictly be shifted to that of the
user; which is where we disagree.  It should be written with no
attachment to either point of view.  Neutral and free of articles is
my preference, because then a reader has the freedom to mentally
insert whatever articles make sense from their point of view.

> I didn't have a real problem with To_The_Stream, and I don't see why
> you do though personally I would have just said To, as I indicated.

To_The_Stream is acceptible, but barely.  It's wordy with all those
articles.  "Target" is more direct, yet short.

>>    procedure Send (Message : in String; Target : in Stream);
>>
>> It's not clutsy from the inside or the outside, it's concise (with
>> no distracting articles), and it doesn't mislead.  It assumes the
>> audience/reader knows Ada.  If the reader doesn't know basic Ada,
>> then the problem is with the reader, not the code.
> 
> I don't see what 'knowing Ada' has to do with it?

I added the parameter modes.  This would still read as "Message
... in", which could mislead a non-Ada reader to interpret it just
like "Message_In" might have been interpretted.  But in my version,
"in" was part of the language, and the reader is responsible for
understanding it.

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Anonymous Coward]

In article <m2acg5i1ko.fsf@grendel.local>, Simon Wright wrote:
> 
>> I also object to the guides comment advising against "Day_Type".
>> It's a very good practice to suffix types with "_Type", "_Record",
>> or "_Array", so it's clear from the identifier what it refers to,
>> and also so you don't hijack a good variable name.  In the above
>> case, "Day" can no longer be used to name an object.
> 
> This is one of the more contentious style arguments. If you work on
> my project, I will insist that you _don't_ stick these useless
> suffices on.

Suffixes are *very* useful, as I will illustrate.  It's no coincidence
that well named, direct, concise type names very often match
(verbatim) good names for objects (including enums), in the absense of
a type suffix.

For example:

   package Name_Collisions is

      type Day is (Monday, Tuesday,  Wednesday, Thursday,
                   Friday, Saturday, Sunday);

      type Meters is new Float;

      type Feet is new Float;

      --Oops, can't use these enums, since they were hijacked for
      --numerical specs.
      --
      type Length is (Feet, Meters, Miles);

      --Oops, can't use these names either, since "day" was hijacked.
      --
      type Timestamp_Component is (Month, Day, Year, Hour, Minute);

      type Speed is new Float;

      --No can do.  "speed" hijacked by type definition.
      --
      Speed : Speed;

   end Name_Collisions;

I've worked on a project that prohibited use of "_Type", and name
collisions like above were a regular irritation, forcing users to
constantly workaround the problem by prefixing "A_" to objects that
needed no specific nomenclature.  Needless to say, the code was quite
ugly, because folks had to attach more junk to the identifier, and
worse, there was no uniform pattern.  Some people would do the "A_",
others would resort to "_Object", and the more disciplined users would
simply replace "_Type" with "_Kind" :]

The other projects I've worked did not ban or impose "_Type".  And in
those situations, programmers naturally adopted the "_Type"
convention, simply because it mitigates name collisions while
simultaneously enhancing readability and style uniformity.  The
"_Type" convention is customary from what I've seen.. folks with
different backgrounds naturally use it as if they were trained to.  So
the Ada Quality and Style book should be updated to pass on the good
customs to beginners.

> And I'm not sure that Day is a good variable name; 

It depends on the situation.  Sometimes you might clearly want a "Day"
object, and more english only serves to confuse or detract from the
operations.  And in other cases more distinction may be in order. 

> if it's not worth giving it a name which indicates its use, what's
> wrong with plain D?

That's too cryptic.. it's a C coding hacker style that has no place in
Ada.  I can't think of any cases where it would make good sense to
strip away its identity like that.

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Martin Dowie]

Anonymous Coward wrote:
>    package Name_Collisions is
>
>       type Day is (Monday, Tuesday,  Wednesday, Thursday,
>                    Friday, Saturday, Sunday);
>
>       type Meters is new Float;
>
>       type Feet is new Float;
>
>       --Oops, can't use these enums, since they were hijacked for
>       --numerical specs.
>       --
>       type Length is (Feet, Meters, Miles);
>
>       --Oops, can't use these names either, since "day" was hijacked.
>       --
>       type Timestamp_Component is (Month, Day, Year, Hour, Minute);
>
>       type Speed is new Float;
>
>       --No can do.  "speed" hijacked by type definition.
>       --
>       Speed : Speed;
>
>    end Name_Collisions;

But why not use scoping to solve this? I always separate type declarations
from object declarations anyway, so I never see these sorts of problems.
Also, I don't think that "Speed" /is/ a good type name e.g.

package SI is
   type Meters_Per_Second is ...;
end SI;

package App is
   Speed : SI.Meters_Per_Second;
   ...
end App;

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Anonymous Coward]

In article <437c5ec8$1_1@glkas0286.greenlnk.net>, 
Martin Dowie wrote:
> Anonymous Coward wrote:
>>    package Name_Collisions is
>>       [...]
>>       type Speed is new Float;
>>
>>       --No can do.  "speed" hijacked by type definition.
>>       --
>>       Speed : Speed;
>>
>>    end Name_Collisions;
> 
> But why not use scoping to solve this? I always separate type
> declarations from object declarations anyway, so I never see these
> sorts of problems.  

I would prefer not to make my architecture dependant on identifier
choices, since packages are much more than just name spaces.  If
package seperation prevents a name collision, it's only incidental in
my case.  

> Also, I don't think that "Speed" /is/ a good
> type name e.g.
> 
> package SI is
>    type Meters_Per_Second is ...;
> end SI;
> 
> package App is
>    Speed : SI.Meters_Per_Second;
>    ...
> end App;

That's getting into the specifics of how a speed might be used.  I
deliberately try to keep my examples as simple as possible to
illustrate my point, so you couldn't see from my example why
Speed(_Type) might be a good name - only why "Speed" alone would be a
bad name.  Here's a slightly more elaborate example:

   package Physics is

      type Distance_Type is private;
      type Speed_Type    is private;
      type Time_Type     is private;

      type Distance_Units_Type is (Meters, Feet, Miles);

      type Time_Units_Type is (Seconds, Minutes, Hours);

      function Distance (Distance       : in Float;
                         Distance_Units : in Distance_Units_Type)
        return Distance_Type;

      function Time (Time       : in Float;
                     Time_Units : in Time_Units_Type)
        return Time_Type;

      function "/" (Left : in Distance_Type; Right : in Time_Type)
        return Speed_Type;

      function "*" (Left : in Speed_Type; Right : in Time_Type)
        return Distance_Type;

      function "*" (Left : in Time_Type; Right : in Speed_Type)
        return Distance_Type;

   private

      type Distance_Type is new Float;
      type Speed_Type    is new Float;
      type Time_Type     is new Float;

   end Physics;

In this case, Speed_Type fully leverages encapsulation to keep units
of measure as abstract as possible.  Internally speed is represented
as meters per second, but that is none of the users business, so
"Speed" suffixed with "_Type" makes the most sense.

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Martin Dowie]

Anonymous Coward wrote:
> In this case, Speed_Type fully leverages encapsulation to keep units
> of measure as abstract as possible.  Internally speed is represented
> as meters per second, but that is none of the users business, so
> "Speed" suffixed with "_Type" makes the most sense.

Or A_Speed... :-)

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Georg Bauhaus]

On Thu, 2005-11-17 at 04:23 +0000, Anonymous Coward wrote:


>    package Name_Collisions is
> 
>       type Day is (Monday, Tuesday,  Wednesday, Thursday,
>                    Friday, Saturday, Sunday);
> 
>       type Meters is new Float;
> 
>       type Feet is new Float;
> 
>       --Oops, can't use these enums, since they were hijacked for
>       --numerical specs.
>       --
>       type Length is (Feet, Meters, Miles);

I think rather than hijacking this is asking for thought:
In you system, in the same place, is Feet a type or an
enumeration literal? Rephrasing Simon's excellent question,
now what *is* the use of Feet in the same namespace? Is it the
best choice to overload Feet here? Is it good style to overload
Feet in the same block?

Is Length to be a collection of types, with the types logically
connected? If so, then why not express this in the program?

  type Length is new Float;

  type Feet is new Length;
  type Meters is new Length;
  type Miles is new Length;

(Yes, this is not an enumeration, but anaway, I'll rather have to
speculate what the intended use of the Length might be.)

Given the above definitions now, what is Meters'Base?
Could you use it like Length to some extent?

Or is Length intended to be a collection of type names?
Symbols a la Lisp?

What if you want to write something using the types' commonalities
and not caring about their specifics? Like in

  package Distance_IO is new Float_IO(Length);

Anyway, the units might be missing from the type definitions.


> I've worked on a project that prohibited use of "_Type", and name
> collisions like above were a regular irritation, forcing users to
> constantly workaround the problem by prefixing "A_" to objects that
> needed no specific nomenclature. 

Workarounds like A_, used throughout the whole program, seem
like laziness to me. They will take revenge later when the same
programmers no long remember the specific context of A_Thing.
What thing?

In a dozen lines or so, a single letter is not at all an
indication of C style hacking, but rather a well established
way of expressing things. Mathematicians do that, technicians
too, and scientist also.

   for D in Day loop
      if Is_Weekday(D) then
         Start_Machinery;
      end;
   end loop;

Anything wrong here with the choice of D?

When I see "The_Day" in e.g. a subprogram profile, I'm tempted
to think of the parameter to be just some day. Fine. Alternatively,

  procedure foo(Day: Day_Type);

requires that the Ada language is kind of extended by a syntax
rule affixing _Type to every type name. Otherwise the reader might
be forced to switch style contexts in the procedure body.
This will be due to the overloading of "Day", because as you have
explained, the word itself is capable of expressing either object
or type.


>  Needless to say, the code was quite
> ugly, because folks had to attach more junk to the identifier, and
> worse, there was no uniform pattern.

Yes, junk is an indication of lack of Q&S. Folks were too lazy
to choose good names guided by some good rules.
If the software is to be maintained for some time, and deadlines
permitting, choice of good names will be more pleasant and money
saving in the long run, I think.

>   Some people would do the "A_",
> others would resort to "_Object", and the more disciplined users would
> simply replace "_Type" with "_Kind" :]

Somehow this discussion reminds me of the type prefix notation
introduced in some Windows C programming books.

  lpszLastName;

"Worse is better" at work?

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Martin Dowie]

Georg Bauhaus wrote:
> Workarounds like A_, used throughout the whole program, seem
> like laziness to me. They will take revenge later when the same
> programmers no long remember the specific context of A_Thing.
> What thing?

It's only a problem if you have variables/parameters with the "A_" prefix.
That's not what I said - only types would have "A_" - just like the real
world! :-)

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Georg Bauhaus]

On Thu, 2005-11-17 at 11:53 +0000, Martin Dowie wrote:
> Georg Bauhaus wrote:
> > Workarounds like A_, used throughout the whole program, seem
> > like laziness to me. They will take revenge later when the same
> > programmers no long remember the specific context of A_Thing.
> > What thing?
> 
> It's only a problem if you have variables/parameters with the "A_" prefix.
> That's not what I said - only types would have "A_" - just like the real
> world! :-)
> 

Right, sorry. I should have stressed that I was referring
to variable parameters names and the like.

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Brian May]

>>>>> "Georg" == Georg Bauhaus <bauhaus@futureapps.de> writes:

    Georg> Somehow this discussion reminds me of the type prefix notation
    Georg> introduced in some Windows C programming books.

    Georg> lpszLastName;

That is a style that was used, I believe, by Microsoft, in Windows 2
(probably 1.0) days. Its possible it first came from IBM (or
Microsoft?)  in OS/2 1.0 (my memory isn't that good). I believe the
windows include files still use it.

It was decided that it helped if you were reminded what type the
variable is whenever you go to use it. Perhaps overused. I am not sure
there is even a distinction between "long pointers" (lp) and "short
pointers" anymore with 32 bit software (not counting low level device
drivers and OS code), but the names seem to remain. Also, how often do
you encounter a string in C that isn't null terminated (sz)?

Possibly this style was influenced by lack of type safety, especially
in early C compilers.

Also, you could have two variables:
spszLastName
lpszLastName

To signify that one is a short pointer and one is a long pointer to
the same data.

However, sometimes it still helps to add a type prefix/postfix to a
variable, if for example two or more variables contain the some data
but different types for example.

type kilometres_per_hour ...;
type miles_per_hour ...;

....

vehicle_speed_kps := convert(vehicle_speed_mph);

or even:

kps := convert(mph);

Is easier to understand then what I often see happen:

car_speed := convert(vehicle_speed);

What units was car_speed again? What units was vehicle speed? What is
this convert doing? Gee - I need the speed in meters_per_second
too. Lets create a new variable temp_1_car_speed. Now I need to
calculate the "wind speed" of the car (yes - dumb example - I don't
know why you would want to do this, unless the car can fly or drive
over water). temp_2_car_speed. Hang on. This code also works for
trucks, too. Who cares, its just a variable name...

Next month, somebody takes over the code: "This code is a complete
mess - It is going to be much quicker if I just rewrite the code
instead of trying to work out what all of these temp_n_variable do. I
will give better variable names like variable_temp_b instead, and
document everything on this scrap piece of paper. Did anyone see where
I put it?" <grin>.


It is interesting that the decided to remove spaces, and replace make
the next letter uppercase. I don't like this when you have to encode
an abbreviation in the function name:

MakeHtmlForPage

seems wrong, as it is HTML not Html, however, this is worse:

MakeHTMLForPage

Is the abbreviation HTMLF?

Unfortunately, this style seems to be required for CORBA (as
underscore is used for a special purpose in the C bindings).

Enough of my raving.
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Martin Dowie]

Brian May wrote:
> It was decided that it helped if you were reminded what type the
> variable is whenever you go to use it.

And what happens when the type changes, say from an integer to a float - do
you _really_want to have to change everywhere it is used? What about legacy
products?

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Marc A. Criley]

Martin Dowie wrote:
> Brian May wrote:
> 
>>It was decided that it helped if you were reminded what type the
>>variable is whenever you go to use it.
> 
> 
> And what happens when the type changes, say from an integer to a float - do
> you _really_want to have to change everywhere it is used? What about legacy
> products?

According to Joel Spolsky of "Joel On software", some Microsoft 
technical writers misunderstood a key term in Charles Simonyi's paper 
describing what came to be known as "Hungarian Notation".  Simonyi 
inappropriately used the word "type" when he meant "kind", and "type" 
was interpreted to mean "data type", like integer, float, and so on, 
when he'd intended it as a prefix to signal the _kind_ of thing, like 
"ix" for indices, "col" for variables containing column numbers, and 
"rw" for variables containing row numbers.

Joel describes how Hungarian notation got wrecked in "Making Wrong Code 
Look Wrong" (http://www.joelonsoftware.com/articles/wrong.html).

-- Marc A. Criley
-- McKae Technologies
-- www.mckae.com
-- DTraq - XPath In Ada - XML EZ Out

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Martin Dowie]

Marc A. Criley wrote:
> According to Joel Spolsky of "Joel On software", some Microsoft
> technical writers misunderstood a key term in Charles Simonyi's paper
> describing what came to be known as "Hungarian Notation".  Simonyi
> inappropriately used the word "type" when he meant "kind", and "type"
> was interpreted to mean "data type", like integer, float, and so on,
> when he'd intended it as a prefix to signal the _kind_ of thing, like
> "ix" for indices, "col" for variables containing column numbers, and
> "rw" for variables containing row numbers.
>
> Joel describes how Hungarian notation got wrecked in "Making Wrong
> Code Look Wrong" (http://www.joelonsoftware.com/articles/wrong.html).

Yes, I've got that book - a very enjoyable read and even if none of his
advice is particularly new, at least it puts it into one handy tomb.

Cheers

-- Martin

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Brian May]

>>>>> "Marc" == Marc A Criley <mcNOSPAM@mckae.com> writes:

    Marc> Joel describes how Hungarian notation got wrecked in "Making
    Marc> Wrong Code Look Wrong"
    Marc> (http://www.joelonsoftware.com/articles/wrong.html).

Looks like a good article.

In a strongly typed language, I would prefer to use different types,
so the compiler does the checking.

However, if you have to use a language that isn't strongly typed, good
Hungarian notation looks like a good compromise.

With respect to his complaint on exception handling - I like the Java
model where every exception that can be raised by a function has to be
declared - that way you don't have to check for exceptions that don't
currently occur - and if the specifications change, the compiler can
generate an error to let you know that you may not have considered an
exception. I think it is a limitation of the Ada exception handling
model that a function can raise any exception - including exceptions
that are outside the scope of the caller. Nor does Ada have a
"finally" clause.

(yes, I realize some people hate this...)
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Maciej Sobczak]

Brian May wrote:

>     Marc> (http://www.joelonsoftware.com/articles/wrong.html).
> 
> Looks like a good article.

I agree, but there is some bias in it, see below.

> 
> In a strongly typed language, I would prefer to use different types,
> so the compiler does the checking.

I fully agree. Making wrong code *look* wrong is a good idea, but it is 
only half of the solution. Complete solution is making wrong code *fail 
to validate* in the automated way (compilation belongs to this).

> However, if you have to use a language that isn't strongly typed, good
> Hungarian notation looks like a good compromise.

Fully agreed. The problem with this article is that it does not name the 
languages to which it mostly applies and instead makes an impression 
that it applies to every language. Certainly Hungarian notation (in its 
original sense) is a good compromise in C, PHP, Perl and other languages 
where you cannot express separate domains with separate types.
But I consider it to be useless for languages that provide the way to 
separate domains of interest by defining separate types, possibly with 
dedicated functions as the only gateways for conversions between those 
domains. Ada is such a language. C++ is also such a language and the 
problem with this article is that it might suggest the opposite to those 
who don't know it.

> With respect to his complaint on exception handling - I like the Java
> model where every exception that can be raised by a function has to be
> declared [...]

Except that the exception is not necessarily a contract between the 
direct caller and that function. Consider the sorting procedure, which 
accepts, as a parameter, a comparator which might throw some exception:

Caller -- catches/handles exception

    -> Sorting_Function(array, comparator)

          -> comparator.Compare(...) -- throws/raises exception

The type of this exception is actually a contract between the caller of 
sorting function and the comparator. The sorting function itself should 
be completely transparent w.r.t. exception that is thrown/raised by 
comparator and catched/handled by the caller. Java got it wrong.

 > Nor does Ada have a
> "finally" clause.

Ada doesn't need it (nor C++).
Finalizers + object lifetime controlled by scope is a superior tool.


-- 
Maciej Sobczak : http://www.msobczak.com/
Programming    : http://www.msobczak.com/prog/

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Marc A. Criley]

Maciej Sobczak wrote:
> Brian May wrote:
> 
>>     Marc> (http://www.joelonsoftware.com/articles/wrong.html).
>>

> Fully agreed. The problem with this article is that it does not name the 
> languages to which it mostly applies and instead makes an impression 
> that it applies to every language. Certainly Hungarian notation (in its 
> original sense) is a good compromise in C, PHP, Perl and other languages 
> where you cannot express separate domains with separate types.
> But I consider it to be useless for languages that provide the way to 
> separate domains of interest by defining separate types, possibly with 
> dedicated functions as the only gateways for conversions between those 
> domains. Ada is such a language. C++ is also such a language and the 
> problem with this article is that it might suggest the opposite to those 
> who don't know it.

And I agree with this.  I, and Hyman too I expect, cited the article for 
its brief history lesson on how Hungarian Notation get messed up.

On the use of naming as a means to improve code quality, I'm just 
grateful to be using Ada and strong typing :-)

Regarding www.joelonsoftware.com in general, though, Spolsky does write 
well and intelligently -- and he's a successful businessman.  I 
recommend working your way through his article archive.

-- Marc A. Criley
-- McKae Technologies
-- www.mckae.com
-- DTraq - XPath In Ada - XML EZ Out

Java exception model. Was: Re: Ada Quality and Style book discussion ("_Type" suffix)

[Peter C. Chapin]

Brian May wrote:

> With respect to his complaint on exception handling - I like the Java
> model where every exception that can be raised by a function has to be
> declared - that way you don't have to check for exceptions that don't
> currently occur - and if the specifications change, the compiler can
> generate an error to let you know that you may not have considered an
> exception.

The problem with Java's model is that it forces the programmer to deal 
in some way with exceptions that semantically can't happen. Consider

procedure Outer is
begin
   if Some_Complicated_Check then
     Inner;
   end if;
end Outer;

Suppose procedure Inner raises an exception under certain conditions yet 
can't do so in the code above because Inner is only executed when the 
complicated check succeeds. Assume that under those particular 
conditions, it will never fail. The Java exception model would require 
us to either handle an exception that will never occur, or declare that 
Outer might raise an exception that we know it will never raise. Such a 
declaration will force Outer's callers to also do something about this 
impossible exception as well, etc, and so forth.

The example above is simplistic and contrived but it's my belief that in 
real programs this sort of issue comes up a lot.

I agree with the quoted article, though, in that using exceptions 
properly is surprisingly tricky and that it does require the programmer 
to think about non-local issues. I think there are times when the old 
fashion method of returning error codes is probably better. However, a 
blanket prohibition against exceptions is probably an over reaction.

Peter

Re: Java exception model. Was: Re: Ada Quality and Style book discussion ("_Type" suffix)

[Dmitry A. Kazakov]

On Fri, 18 Nov 2005 11:48:46 GMT, Peter C. Chapin wrote:

> Brian May wrote:
> 
>> With respect to his complaint on exception handling - I like the Java
>> model where every exception that can be raised by a function has to be
>> declared - that way you don't have to check for exceptions that don't
>> currently occur - and if the specifications change, the compiler can
>> generate an error to let you know that you may not have considered an
>> exception.
> 
> The problem with Java's model is that it forces the programmer to deal 
> in some way with exceptions that semantically can't happen. Consider
> 
> procedure Outer is
> begin
>    if Some_Complicated_Check then
>      Inner;
>    end if;
> end Outer;
> 
> Suppose procedure Inner raises an exception under certain conditions yet 
> can't do so in the code above because Inner is only executed when the 
> complicated check succeeds. Assume that under those particular 
> conditions, it will never fail. The Java exception model would require 
> us to either handle an exception that will never occur, or declare that 
> Outer might raise an exception that we know it will never raise. Such a 
> declaration will force Outer's callers to also do something about this 
> impossible exception as well, etc, and so forth.

I can't tell for Java, but let consider Ada adopting a contract model of
exceptions. Your reasoning above is flawed. If the designer of Outer knows
that the exception X cannot propagate out of it then it should be:

procedure Outer is
begin
   if Some_Complicated_Check then
      begin
         Inner;
      exception
         when X => -- This is not a state, it is a bug
            raise Program_Error;
      end if;
   end if;
end Outer;

> The example above is simplistic and contrived but it's my belief that in 
> real programs this sort of issue comes up a lot.

I think it is a software design issue. When exceptions and exceptional
states are considered as *valid* states, then there cannot be any good
argument against contract model of exceptions. They belong to a
*functional* part of the program. What is left, are the arguments like - it
is too difficult to implement; there would be too big overhead; I don't
know how to do it right - not much impressive. Alternatively you can say,
OK, exceptions are exclusively for software bugs. But this is also a quite
weak position, because if they are bugs, then why would you like to handle
them? Bugs to be debugged!

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Java exception model. Was: Re: Ada Quality and Style book discussion ("_Type" suffix)

[Peter C. Chapin]

Dmitry A. Kazakov wrote:

> I can't tell for Java, but let consider Ada adopting a contract model of
> exceptions. Your reasoning above is flawed. If the designer of Outer knows
> that the exception X cannot propagate out of it then it should be:
> 
> procedure Outer is
> begin
>    if Some_Complicated_Check then
>       begin
>          Inner;
>       exception
>          when X => -- This is not a state, it is a bug
>             raise Program_Error;
>       end if;
>    end if;
> end Outer;

One of the arguments for exceptions is that they simplify error 
handling. I'm not sure code above is much of a simplification over 
traditional methods. For example, I don't really want to be forced into 
the style above for Constraint_Error every time I index into an array. 
In any case, using the Java model procedure Outer would have to declare 
that it might raise Program_Error. Do you really want to force 
programmers to put such declarations on every subprogram? That would 
render those declarations pointless, wouldn't it?

Actually in Java, some exceptions are unchecked... like the null 
reference exception... because it's clear that forcing programmers to 
either handle it or declare it as thrown in every method would be 
excessive. A program would be littered with "useless" handlers or else 
every single method written would have to say that it might throw a null 
reference. Java thus has two classes of exceptions: those that are 
checked and those that are not. How does one decide into which class a 
new exception should go?

The whole issue seems like a nasty morass to me.

Peter

Re: Java exception model. Was: Re: Ada Quality and Style book discussion ("_Type" suffix)

[Dmitry A. Kazakov]

On Sat, 19 Nov 2005 18:06:05 GMT, Peter C. Chapin wrote:

> Dmitry A. Kazakov wrote:
> 
>> I can't tell for Java, but let consider Ada adopting a contract model of
>> exceptions. Your reasoning above is flawed. If the designer of Outer knows
>> that the exception X cannot propagate out of it then it should be:
>> 
>> procedure Outer is
>> begin
>>    if Some_Complicated_Check then
>>       begin
>>          Inner;
>>       exception
>>          when X => -- This is not a state, it is a bug
>>             raise Program_Error;
>>       end if;
>>    end if;
>> end Outer;
> 
> One of the arguments for exceptions is that they simplify error 
> handling. I'm not sure code above is much of a simplification over 
> traditional methods. For example, I don't really want to be forced into 
> the style above for Constraint_Error every time I index into an array.

What does Constraint_Error mean in the program context? The same simple
question again: is it a legal outcome of indexing and thus of the
subroutine that does it? If yes, then you need not to catch it. If it is
not, then why do you let it propagate?

BTW, Constraint_Error is an exception I would most like to be checked. In
Ada it is not always obvious whether Constraint_Error is a possible
outcome.

> In any case, using the Java model procedure Outer would have to declare 
> that it might raise Program_Error.

No. Because Program_Error above is just a place holder for an exception
that cannot be handled, replace it with Abort_This_Rubbish. Or else it
should be:

procedure Outer is
begin
   if Some_Complicated_Check then
      begin
         Inner;
      exception
         when X =>
            -- This is a state, I know how to handle it HERE!
      end if;
   end if;
end Outer;

> Do you really want to force 
> programmers to put such declarations on every subprogram? That would 
> render those declarations pointless, wouldn't it?
>
> Actually in Java, some exceptions are unchecked... like the null 
> reference exception... because it's clear that forcing programmers to 
> either handle it or declare it as thrown in every method would be 
> excessive. A program would be littered with "useless" handlers or else 
> every single method written would have to say that it might throw a null 
> reference. Java thus has two classes of exceptions: those that are 
> checked and those that are not.

I think it is reasonable. What Java probably lacks is a good way of
composition of exception contracts, like "X raises what Y does except that
ones mentioned in Z."

> How does one decide into which class a 
> new exception should go?

Checked. I cannot imagine any unchecked exception other than generated by
the environment (hardware/OS.)

> The whole issue seems like a nasty morass to me.

I don't think so. What could be alternative? Both in Ada and in C++
managing exceptions becomes a problem in large projects. I think each
practitioner can remember a pair of horror stories about exceptions
propagating during library elaboration or in destructors.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Java exception model. Was: Re: Ada Quality and Style book discussion ("_Type" suffix)

[Brian May]

>>>>> "Dmitry" == Dmitry A Kazakov <mailbox@dmitry-kazakov.de> writes:

    >> How does one decide into which class a new exception should go?

    Dmitry> Checked. I cannot imagine any unchecked exception other
    Dmitry> than generated by the environment (hardware/OS.)

I think It also depends on how likely this error is going to occur,
and if you want to be able to handle this error condition gracefully
in your code or not.

So something like "CRC error" in a received packet would definitely
get checked, because you don't want your program to collapse in a heap
if it receives a corrupt packet.

If however, after checking the CRC, you check it again (maybe for
paranoid reasons inside lower level functions) using some sort of
assert statement, and it is now wrong, you may decide this condition
should never occur (implies some sort of software bug or hardware
error), and you don't want to try and recover from this condition. In
fact, you may even want to abort immediately without trying to clean
up anything.

So if an exception is a result of a non-recoverable software bug or a
non-recoverable hardware error, it probably should go
unchecked. Otherwise it should be checked.
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Java exception model. Was: Re: Ada Quality and Style book discussion ("_Type" suffix)

[Brian May]

>>>>> "Dmitry" == Dmitry A Kazakov <mailbox@dmitry-kazakov.de> writes:

    Dmitry> I think it is reasonable. What Java probably lacks is a
    Dmitry> good way of composition of exception contracts, like "X
    Dmitry> raises what Y does except that ones mentioned in Z."

One issue that is not always clear is how exceptions should be handled
low level routines.

For example, append_mail might be a function that writes a new email
to the users mailbox. Initially the designers decide it might through the
following exceptions:

ERROR_QUOTA_EXCEEDED
ERROR_PERMISSION_DENIED

Later on, the function is expanded to support different formats, e.g.
LMTP, IMAP, etc.

Eventually, one day, a low level routine used by append_mail returns
the exception:

ERROR_OUT_OF_PAPER

What does append_mail do?


It could:

a) return ERROR_OUT_OF_PAPER to calling subroutine, but should the
calling subroutine really have to deal with a printer error? It
doesn't even know the output is going to a printer. Also, should it
really have to deal with network errors? What about LDAP errors,
Kerberos authentication errors, errors creating temporary files, etc?

Yes, it could catch all exceptions, just in case; I am not convinced
this is a good solution.

b) turn the exception into a generic exception for append_mail,
ERROR_APPEND_MAIL, this might make it harder to locate the actual
source of the exception. This I think is my preferred solution, as I
consider the above exceptions private implementation details inside
append_mail, all that the calling function is interested in is the
fact an error occurred, and possibly a string to display to the user
(but see below).

At least with the Java model, the compiler lets you know of the issue,
and you don't suddenly wake up to the fact these low level exceptions
are suddenly being used throughout your entire code.



Then, if the calling process has to generate an error to the sender,
what should the error be?

If I sent an email to somebody and got an error "Out Of Paper", I
think I might be slightly confused. Another alternative is to prefix
the message at each layer, eg:

"Error appending mail: Error sending email via LMTP: Error storing mail: Error logging email: Error writing to syslog: Error writing to printer: Out of paper."

You just need to be able to interpret such a message... I think many
users I know would still be confused, especially as it deals with
technical details specific to the mail setup of the recipient. It
probably would help the administrator though, if he ever receives a
copy of the error.

(yes, you could argue that the above error shouldn't be a fatal error,
lets assume paranoid people).

The other approaches I have seen are hardly worth mentioning:

* generic error for all errors, e.g. "Error!"

* assume error is, say incorrect password, and display verbose
  information on what the user should do to fix an incorrect password.

  (IIRC Outlook does this when accessing a remote IMAP server - and
  the user spends ages trying to work out why the password is wrong
  when the real error is totally unrelated.)
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Simon Wright]

Brian May <bam@snoopy.apana.org.au> writes:

> exception. I think it is a limitation of the Ada exception handling
> model that a function can raise any exception - including exceptions
> that are outside the scope of the caller.

I found a use for this ..

separate (A.B.C)
procedure D is
  Unimplemented : exception;
begin
   raise Unimplemented;
   null;
end D;

has (in GNAT) the pleasing effect of reporting an exception named
A.B.C.D.Unimplemented -- very helpful for tracing things down!

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Hyman Rosen]

Brian May wrote:
> It was decided that it helped if you were reminded what type the
> variable is whenever you go to use it.
...
> However, sometimes it still helps to add a type prefix/postfix to a variable

Actually, this second use is what Hungarian notation was
intended to be. It was bastardized into the useless first form
by people who didn't understand what they were doing.

See <http://www.joelonsoftware.com/printerFriendly/articles/Wrong.html>.

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Jeffrey R. Carter]

Anonymous Coward wrote:
> Suffixes are *very* useful, as I will illustrate.  It's no coincidence
> that well named, direct, concise type names very often match
> (verbatim) good names for objects (including enums), in the absense of
> a type suffix.

GOOD suffixes are very useful. _Type is a bad suffix. As AC himself says 
elsewhere, "If you're repeating information from your declaration in your 
identifiers, then you've created a maintenance problem by introducing too much 
noise". "type X_Type" clearly repeats information from the declaration in the 
identifier.

Prefixes are very bad. The 1st few characters of an identifier are the most 
important in determining what it is. If lots of identifiers start with the same 
sequence of characters, it makes reading harder.

My personal preferences are

>       type Day is (Monday, Tuesday,  Wednesday, Thursday,

Day_ID

>       type Meters is new Float;

Meter_Value

>       type Feet is new Float;

Foot_Value

>       type Length is (Feet, Meters, Miles);

Length_ID

>       Speed : Speed;

Global variables are extremely bad. But consider

procedure P (Speed : in Speed_Value);

In well designed systems, packages tend to contain a type and operations on that 
type; objects of the type are generally declared elsewhere, and in any case 
represent specific things, not the general concept of the type, so the issue 
rarely comes up.

That said, I've worked on projects where _Type was mandated, and it works 
reasonably well. I got irritated every time I typed _Type, but the resulting 
code was readable.

-- 
Jeff Carter
"I'm a kike, a yid, a heebie, a hook nose! I'm Kosher,
Mum! I'm a Red Sea pedestrian, and proud of it!"
Monty Python's Life of Brian
77

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Dmitry A. Kazakov]

On Sun, 20 Nov 2005 19:41:05 GMT, Jeffrey R. Carter wrote:

> Anonymous Coward wrote:
>> Suffixes are *very* useful, as I will illustrate.  It's no coincidence
>> that well named, direct, concise type names very often match
>> (verbatim) good names for objects (including enums), in the absense of
>> a type suffix.
> 
> GOOD suffixes are very useful. _Type is a bad suffix. As AC himself says 
> elsewhere, "If you're repeating information from your declaration in your 
> identifiers, then you've created a maintenance problem by introducing too much 
> noise". "type X_Type" clearly repeats information from the declaration in the 
> identifier.

True, Hungarian notation is bad.

> Prefixes are very bad. The 1st few characters of an identifier are the most 
> important in determining what it is. If lots of identifiers start with the same 
> sequence of characters, it makes reading harder.

Yes, prefix Hungarian notation is worse than bad.

> My personal preferences are
> 
>>       type Day is (Monday, Tuesday,  Wednesday, Thursday,
> 
> Day_ID

Is Monday an ID?

>>       type Meters is new Float;
> 
> Meter_Value

Type is a value, how so?

Meter_Value is something like 1000mm, or the length of that metal bar
somewhere in Paris (I guess), or the distance traveled by light in vacuum
during a time interval of 1/299 792 458 of a second... (:-))

I would prefer

   type Metric_Distance is new Float;

if it is necessary to underline that the distance is measured in meters.

> procedure P (Speed : in Speed_Value);

   procedure P (Speed_Value : in Speed);

I presume. But better is:

   procedure P (Value : in Speed);

--------------
The problem is that both type and variable of are meant to identify the
same thing: a set of values. When an object is declared one can try to name
it in a way that would reflect the specific value it represents:

Today : Day;
Tomorrow : Day;

With subroutine parameters it gets difficult. More abstract they are more
difficult is to find a name reflecting the problem space. In the end it
becomes: Value, Index, I, J, K, X, Y, Left, Right, Result etc.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Quality and Style book discussion ("_Type" suffix)

[Simon Wright]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> writes:

> On Sun, 20 Nov 2005 19:41:05 GMT, Jeffrey R. Carter wrote:
>
>> Anonymous Coward wrote:

>>>       type Meters is new Float;
>> 
>> Meter_Value

> I would prefer
>
>    type Metric_Distance is new Float;
>
> if it is necessary to underline that the distance is measured in
> meters.

If that was the case then AC's name is best (modulo spelling, we Brits
would use Metres), after all kilometres are metric distances too.

Re: Ada Quality and Style book discussion

[Marc A. Criley]

Anonymous Coward wrote:

> I'm surprized that section 2.1.5 permits:
> 
>    procedure Display_Menu_On_Screen (
>          Title   : in     String;
>          Options : in     Menus;
>          Choice  :    out Alpha_Numerics
>        );
> 
> The last line needlessly kills a line, and I always thought ending a
> line with an open grouping symbol (like "(") is pretty ugly.

The situation in which this works is when you're providing a comment for 
each parameter -- if you deem commenting each parameter a worthwhile 
thing to do:-)  The benefit of doing that is when you're using a tool 
like AdaBrowse to go in and extract documentation from your code.  It 
will pull those comments out and make them part of your docs.  Of 
course, you want to do good commenting up front if you're going to do that.

So this definition would actually look something like this if I were 
doing it:

   procedure Display_Menu_On_Screen (
         Title   : in     String;
	-- Menu title, should be concise

         Options : in     Menus;
         -- Menu options, sub-menus are not supported

         Choice  :    out Alpha_Numerics
	-- Numeric index of the chosen option, -1 if menu selection
         -- was canceled
       );

-- Marc A. Criley
-- McKae Technologies
-- www.mckae.com
-- DTraq - XPath In Ada - XML EZ Out