Why .ads as well as .adb?

Why .ads as well as .adb?

[John Perry]

Hello

I understand that Ada, like Modula-2 and Modula-3, and arguably like C++, requires a definition file (.ads) as well as an implementation file (.adb). With Oberon, Wirth moved away from definition files, using a symbol to indicate which module identifiers should be exported. (Someone else may have done this before him; it's just that I'm most familiar with this history.) Most languages I'm familiar with these days do something similar, either via public/private or some other mechanism.

As far as I can tell, though, Ada has stuck with the two separate files, rather than, say, generating an .ads from an .adb with export markup.

Is there a reason Ada hasn't moved to this simpler structure?

john perry

Re: Why .ads as well as .adb?

[J-P. Rosen]

Le 02/06/2019 à 02:48, John Perry a écrit :
> I understand that Ada, like Modula-2 and Modula-3, and arguably like
> C++, requires a definition file (.ads) as well as an implementation
> file (.adb). With Oberon, Wirth moved away from definition files,
> using a symbol to indicate which module identifiers should be
> exported. (Someone else may have done this before him; it's just that
> I'm most familiar with this history.) Most languages I'm familiar
> with these days do something similar, either via public/private or
> some other mechanism.
> 
> As far as I can tell, though, Ada has stuck with the two separate
> files, rather than, say, generating an .ads from an .adb with export
> markup.
> 
> Is there a reason Ada hasn't moved to this simpler structure?
> 

Yes. Because it is by far superior.

One of the main (huge) benefits of Ada is in being able to use
specifications even before the body exists. You can:
1) write the specification, compile it to make sure that it make sense
2) write the code that uses the specification, to make sure that the
specification meets the needs of the using code
3) Write the body, with the assurance that what you do is the right thing.

You can even add:
2.5) write a prototype body to check that the behaviour is correct,
before writing the full body that meets all requirements.

As a teacher, I keep fighting with students who jump to writing bodies
too early.

-- 
J-P. Rosen
Adalog
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
http://www.adalog.fr

Re: Why .ads as well as .adb?

[Dmitry A. Kazakov]

On 2019-06-02 02:48, John Perry wrote:

> I understand that Ada, like Modula-2 and Modula-3, and arguably like C++, requires a definition file (.ads) as well as an implementation file (.adb). With Oberon, Wirth moved away from definition files, using a symbol to indicate which module identifiers should be exported. (Someone else may have done this before him; it's just that I'm most familiar with this history.) Most languages I'm familiar with these days do something similar, either via public/private or some other mechanism.

It is general design principle of separation specifications from 
implementations. Are you arguing against the principle or against 
keeping these things separately. The latter has evident advantages for 
code base maintenance, team development, testing, separate compilation 
etc. BTW, you can stuff bodies and specifications in the same file. It 
is purely compiler's business. See gnatchop for GNAT. So I consider it 
is the former you are against.

> As far as I can tell, though, Ada has stuck with the two separate files, rather than, say, generating an .ads from an .adb with export markup.

That is not possible. You cannot generate specification from 
implementation and conversely. In both cases there is additional 
information missing. It could be two different languages. Even in the 
languages that confuse these things, declarations have syntax different 
from definitions. Compare also Ada's declarative regions with C++'s 
ad-hoc declarations:

    declare
       X : Integer;
    begin
       ... -- Some code
       X := 1;
    end;

    {
       ... // Some code
       int X;
       X = 1;
    }

> Is there a reason Ada hasn't moved to this simpler structure?

See J-P's post. BTW when writing OS-dependent code it is very convenient 
to have one *.ads file and several *.adb files. It ensures that all 
client code is OS-independent, since it sees only the *.ads. And, in the 
tool-chain you just switch to another *.adb when changing the target. 
Compare that with C++'s #ifdef infestations.

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

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> That is not possible. You cannot generate specification from 
> implementation and conversely.

Yes, you can. You can generate specs from implementations.

> In both cases there is additional 
> information missing.

Why is it missing? What if we put all information in implementation? Then there is nothing missing and we can generate specs from it.

Your argument is not convincing. It can be expanded into:
- I have separate spec and implementation files, so I can write my contracts in the spec and then I don't have to repeat them in bodies.
- Well, I did not write my contracts in bodies, so they are not there and therefore something is missing, so I cannot generate specs from it.

?

> Compare also Ada's declarative regions with C++'s 
> ad-hoc declarations:
> 
>     declare
>        X : Integer;
>     begin
>        ... -- Some code
>        X := 1;
>     end;
> 
>     {
>        ... // Some code
>        int X;
>        X = 1;
>     }

When I compare these two examples, I see that C++ is more readable, because it allows me to minimize the scope of names that are not needed until in later parts of code, without messing with useless constructs like this:

begin
   -- some code
   declare
      X : Integer;
   begin
      X := 1;
   end;
end;

There is *nothing* gained in this construct and it is equivalent to the C++ example above.

> BTW when writing OS-dependent code it is very convenient 
> to have one *.ads file and several *.adb files.

I do that in C++, too.

> And, in the 
> tool-chain you just switch to another *.adb when changing the target.

And, in the tool-chain you just switch to another *.cpp when changing the target.
 
> Compare that with C++'s #ifdef infestations.

What? Why would anybody do that, apart from those few cases where this approach genuinely improves the readability of the code and where having separate compilation units would actually be more difficult to maintain?

In other words: for multiplatform development, C++ gives me 2 solutions and I can choose the one which is more beneficial in the given context. Ada offers only one. How is this better?

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[J-P. Rosen]

Le 03/06/2019 à 09:35, Maciej Sobczak a écrit :
>> That is not possible. You cannot generate specification from 
>> implementation and conversely.
> 
> Yes, you can. You can generate specs from implementations.
> 
If you have a body with many subprograms, how can you tell which ones
are intended to be exported, and which ones are private to the body?

>> Compare also Ada's declarative regions with C++'s 
>> ad-hoc declarations:
>>
>>     declare
>>        X : Integer;
>>     begin
>>        ... -- Some code
>>        X := 1;
>>     end;
>>
>>     {
>>        ... // Some code
>>        int X;
>>        X = 1;
>>     }
> 
> When I compare these two examples, I see that C++ is more readable,
because it allows me to minimize the scope of names that are not needed
until in later parts of code, without messing with useless constructs
like this:
> 
> begin
>    -- some code
>    declare
>       X : Integer;
>    begin
>       X := 1;
>    end;
> end;
I don't agree. Yes, Ada is more verbose, but it tells you clearly what
is a declaration, and what are executable statements. In C/C++ , there
is this "Oh, this is a statement, let's assume we have left the
declarations part" that I don't like. Granted, it's a matter of taste.

-- 
J-P. Rosen
Adalog
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
http://www.adalog.fr

Re: Why .ads as well as .adb?

[Keith Thompson]

"J-P. Rosen" <rosen@adalog.fr> writes:
[...]
> I don't agree. Yes, Ada is more verbose, but it tells you clearly what
> is a declaration, and what are executable statements. In C/C++ , there
> is this "Oh, this is a statement, let's assume we have left the
> declarations part" that I don't like. Granted, it's a matter of taste.

There is no "declarations part".  C++ allows declarations and statements
to be mixed within a block.  (C does too, since the 1999 standard.)
Declarations and statements are syntactically distinct, so there's no
ambiguity.

    void func() {
        int x;                 // declaration
        x = 42;                // statement
        printf("x = %d\n", x); // statement
        int y = 43;            // declaration
        printf("y = %d\n", y); // statement
    }

That's inside a function definition.  Outside a function definition,
declarations are allowed and statements are not.  And declarations can
involve execution of code (as in Ada).

Yes, it's a matter of taste, and I'm not arguing for one approach over
the other.

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> If you have a body with many subprograms, how can you tell which ones
> are intended to be exported, and which ones are private to the body?

By annotating them appropriately? Keywords "private" or "export" or similar are commonly used for this purpose.

Please note that your question could also refer to the concept of DLLs, which is not directly addressed by Ada (nor C++). Yet, somehow we do manage to solve this problem.

> I don't agree. Yes, Ada is more verbose, but it tells you clearly what
> is a declaration, and what are executable statements.

I agree with the answer that Keith already wrote for this.

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[Dmitry A. Kazakov]

On 2019-06-03 09:35, Maciej Sobczak wrote:
>> That is not possible. You cannot generate specification from
>> implementation and conversely.
> 
> Yes, you can. You can generate specs from implementations.

No. Specification describes a class of implementations. You cannot 
deduce class from its single member.

>> In both cases there is additional
>> information missing.
> 
> Why is it missing? What if we put all information in implementation? Then there is nothing missing and we can generate specs from it.

It is not possible as well. The language of specifications (to be 
useful) must have statements non-existing in the language of 
implementations.

> Your argument is not convincing. It can be expanded into:
> - I have separate spec and implementation files, so I can write my contracts in the spec and then I don't have to repeat them in bodies.

No. The right statement would be: I cannot write contract in the body.

Contract and an implementation of are in two different languages with 
two different domains. They cannot be spelt in a single language.

BTW, this is why Ada's dynamic constraints is not a contract. They are 
implementations of a contract to raise an exception when some Boolean 
expression yields False.

> - Well, I did not write my contracts in bodies, so they are not there and therefore something is missing, so I cannot generate specs from it.
>
> ?

Right.

>> Compare also Ada's declarative regions with C++'s
>> ad-hoc declarations:
>>
>>      declare
>>         X : Integer;
>>      begin
>>         ... -- Some code
>>         X := 1;
>>      end;
>>
>>      {
>>         ... // Some code
>>         int X;
>>         X = 1;
>>      }
> 
> When I compare these two examples, I see that C++ is more readable, because it allows me to minimize the scope of names that are not needed until in later parts of code, without messing with useless constructs like this:
> 
> begin
>     -- some code
>     declare
>        X : Integer;
>     begin
>        X := 1;
>     end;
> end;
> 
> There is *nothing* gained in this construct and it is equivalent to the C++ example above.

The gain is definition of the scope. C++ equivalent, which I would force 
in each C++ programming guideline, would be:

    {
       ... // Some code
       {
          int X;
          X = 1;
          ..
       }
       .. // Some code
    }

>> BTW when writing OS-dependent code it is very convenient
>> to have one *.ads file and several *.adb files.
> 
> I do that in C++, too.
> 
>> And, in the
>> tool-chain you just switch to another *.adb when changing the target.
> 
> And, in the tool-chain you just switch to another *.cpp when changing the target.
>   
>> Compare that with C++'s #ifdef infestations.
> 
> What? Why would anybody do that, apart from those few cases where this approach genuinely improves the readability of the code and where having separate compilation units would actually be more difficult to maintain?

Yes, why? There must be something contagious in #ifdef's, or maybe, it 
just what C/C++ inherently is?

My guess and my point is that this is what you inevitably get without 
proper contracts (=> separated specifications).

> In other words: for multiplatform development, C++ gives me 2 solutions and I can choose the one which is more beneficial in the given context. Ada offers only one. How is this better?

Choice is a burden. Would you can have a water tap with a third choice: 
hot, cold, sulfuric acid?

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

Re: Why .ads as well as .adb?

[Keith Thompson]

"Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> writes:
> On 2019-06-03 09:35, Maciej Sobczak wrote:
>>> That is not possible. You cannot generate specification from
>>> implementation and conversely.
>> 
>> Yes, you can. You can generate specs from implementations.
>
> No. Specification describes a class of implementations. You cannot 
> deduce class from its single member.

I suspect the point is that you *could* have an Ada-like language
in which specifications could be unambiguously generated from
implementations.  You'd need some kind of additional annotation to
specify whether a given declaration is to be exported.

You can't in Ada as it is, because Ada isn't designed that way.

[...]

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[Dmitry A. Kazakov]

On 2019-06-03 21:51, Keith Thompson wrote:
> "Dmitry A. Kazakov" <mailbox@dmitry-kazakov.de> writes:
>> On 2019-06-03 09:35, Maciej Sobczak wrote:
>>>> That is not possible. You cannot generate specification from
>>>> implementation and conversely.
>>>
>>> Yes, you can. You can generate specs from implementations.
>>
>> No. Specification describes a class of implementations. You cannot
>> deduce class from its single member.
> 
> I suspect the point is that you *could* have an Ada-like language
> in which specifications could be unambiguously generated from
> implementations.

That thing would not be specification. E.g. can you generate an Ada or C 
program from x86 machine code. The answer is, yes you can. Would it be 
the original program. No.

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

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> No. Specification describes a class of implementations. You cannot 
> deduce class from its single member.

So what exactly cannot be deduced? Please provide some challenging example.

> It is not possible as well. The language of specifications (to be 
> useful) must have statements non-existing in the language of 
> implementations.

Why not put those statements in the implementation file? The compiler should be smart enough to distinguish them.

> No. The right statement would be: I cannot write contract in the body.

Why? The text editor should not stop you and the compiler should figure out which is which.

> Contract and an implementation of are in two different languages with 
> two different domains. They cannot be spelt in a single language.

What is a single language? A set of keywords with grammar? I can invent the keywords and grammar to cover both needs. Heck, it was already invented, just write them in a single file.

Your arguments are self-contradictory anyway. What about the package declaration in the some declarative part within the implementation file? I can even declare a helper package in the subprogram scope (in its declarative part), so all arguments about the necessity to keep specs and implementation files separate, on the basis that they must be separate "languages", are pointless anyway. Ada already allows to mix everything together, so why pretending to be so pure? The purity is gone already.

> The gain is definition of the scope. C++ equivalent, which I would force 
> in each C++ programming guideline, would be:
> 
>     {
>        ... // Some code
>        {
>           int X;
>           X = 1;
>           ..
>        }
>        .. // Some code
>     }

This is useful if there is a reason to not have X in the second "Some code" part. Especially if X is handling some resource. Otherwise there is no gain.
Still (in both variants), C++ is more readable (the proportion of useful code to the whole is higher).

> Yes, why? There must be something contagious in #ifdef's, or maybe, it 
> just what C/C++ inherently is?

Or maybe this is just what you want it to be, so that Ada looks better?
The problem is - there is nothing stopping you using the same good programming principles and idioms. Especially with regard to physical code design (we have discussed that already (as most of the other things)).

> > In other words: for multiplatform development, C++ gives me 2 solutions and I can choose the one which is more beneficial in the given context. Ada offers only one. How is this better?
> 
> Choice is a burden.

Yet I know how to benefit from it. And I don't want to resign from it.

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[Dmitry A. Kazakov]

On 2019-06-04 10:24, Maciej Sobczak wrote:
>> No. Specification describes a class of implementations. You cannot
>> deduce class from its single member.
> 
> So what exactly cannot be deduced?

The class.

> Please provide some challenging example.

Let x be 1. Deduce the set it belongs to.

    procedure Foo is
    begin
       X := 1; -- What are the type of X, 1,
    end Foo;
----------------
    package Objects is
       type T is mod 45;
       X : T
    end Objects;

    with Objects; use Objects;
    procedure Foo;
----------------
    generic
       X : in out Integer;
    procedure Foo;

etc.

>> It is not possible as well. The language of specifications (to be
>> useful) must have statements non-existing in the language of
>> implementations.
> 
> Why not put those statements in the implementation file? The compiler should be smart enough to distinguish them.

To make programmer's life a bit easier?

>> No. The right statement would be: I cannot write contract in the body.
> 
> Why? The text editor should not stop you and the compiler should figure out which is which.

It is not the body. You can put dried leaves between pages of a book. 
That does not make them text.

>> Contract and an implementation of are in two different languages with
>> two different domains. They cannot be spelt in a single language.
> 
> What is a single language? A set of keywords with grammar?

+ semantics.

> Your arguments are self-contradictory anyway. What about the package declaration in the some declarative part within the implementation file?

That does not change anything in the nature of declarations. They are 
semantically separate and the programming language should keep this 
distinction clear.

>> Yes, why? There must be something contagious in #ifdef's, or maybe, it
>> just what C/C++ inherently is?
> 
> Or maybe this is just what you want it to be, so that Ada looks better?

You mean I have that much influence on designers of C/C++ software, who 
I never met and didn't know they exist? Could I rather switch its focus 
on bankers?

> The problem is - there is nothing stopping you using the same good programming principles and idioms. Especially with regard to physical code design (we have discussed that already (as most of the other things)).

You are asking religious questions, why people keep on doing bad things? 
Though it highlights the difference between specifications (good 
intentions) and implementations (poor behavior).

>>> In other words: for multiplatform development, C++ gives me 2 solutions and I can choose the one which is more beneficial in the given context. Ada offers only one. How is this better?
>>
>> Choice is a burden.
> 
> Yet I know how to benefit from it. And I don't want to resign from it.

Yep, that is what they say...

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

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> > So what exactly cannot be deduced?
> 
> The class.

What if I don't need the virtual "class" and I'm interested in the single instance only? The one that I wrote?
I'd argue this is the most frequent case.

> > Please provide some challenging example.
> 
> Let x be 1. Deduce the set it belongs to.
> 
>     procedure Foo is
>     begin
>        X := 1; -- What are the type of X, 1,
>     end Foo;

This is not a complete code, exactly because the type of X is not known.
But if you declare X so that it is visible where Foo is, then the information is complete and the spec can be generated (which also means it's not needed).

It was stated at the beginning of this discussion that there are languages that do it. Arguing that it cannot be done is simply not convincing - just look at languages where it is already done.

For example - how would your example look in Java?

> To make programmer's life a bit easier?

Isn't it the most important purpose of having programming languages at all?
Do you want to convince me that the purpose of Ada is to make the programmer's life more difficult? Then, I can tell you, there are countless numbers of beginners who are already convinced that this is actually the case.

> That does not change anything in the nature of declarations. They are 
> semantically separate and the programming language should keep this 
> distinction clear.

But we still don't know why it should do it. We know that Ada does (well, only pretends to, I can still mix everything), but we don't know whether this distinction is worth having, especially in the context of experiences gained from using other languages that don't have it.

> You mean I have that much influence on designers of C/C++ software

If you are designing C/C++ software, then I hope so.

I disagree with your argument that in Ada one can have separate *.adb files for different platforms, whereas in C++ one uses #ifdefs. This is just wrong.

> You are asking religious questions, why people keep on doing bad things?

(Lack of) Education might be the answer.

But note that lack of education is also the reason for people to stay unaware of Ada. So we have a choice: educate people to write good C++ or educate people to write Ada.

But choice is a burden. Right? :-)

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[Dmitry A. Kazakov]

On 2019-06-05 11:04, Maciej Sobczak wrote:
>>> So what exactly cannot be deduced?
>>
>> The class.
> 
> What if I don't need the virtual "class" and I'm interested in the single instance only? The one that I wrote?
> I'd argue this is the most frequent case.

Class in mathematical sense, a set of certain structure. As for 
singleton class yes, it represents itself. But that is extremely rare 
and unrealistic. Would you never wanted to change anything? Once you 
urged to change anything then you do not have it singleton. You have 
some set of implementations (class) and some constant part for the 
clients (interface).

>>> Please provide some challenging example.
>>
>> Let x be 1. Deduce the set it belongs to.
>>
>>      procedure Foo is
>>      begin
>>         X := 1; -- What are the type of X, 1,
>>      end Foo;
> 
> This is not a complete code, exactly because the type of X is not known.

Yes, the specification is missing.

> But if you declare X so that it is visible where Foo is, then the information is complete and the spec can be generated (which also means it's not needed).

You want to me to write the specification down, so that you could 
"deduce" it? That proves my point. You cannot deduce the specification:

    generic
       X : in out Integer;
    procedure Foo;

> For example - how would your example look in Java?

No I idea. I am making a universal point. Whatever language it is, you 
want to limit effects of code modification and to support cooperative 
developing process, you must distinguish specifications and 
implementations on many different levels, not only on the level of 
compilation units. Information hiding, abstraction, reuse, generic 
programming etc just follow.

>> To make programmer's life a bit easier?
> 
> Isn't it the most important purpose of having programming languages at all?
> Do you want to convince me that the purpose of Ada is to make the programmer's life more difficult? Then, I can tell you, there are countless numbers of beginners who are already convinced that this is actually the case.

I don't object. Beginners have different understanding of what software 
design process is and what helps the process and what does not. Their 
understanding is naturally all wrong, otherwise they would not be beginners.

>> That does not change anything in the nature of declarations. They are
>> semantically separate and the programming language should keep this
>> distinction clear.
> 
> But we still don't know why it should do it.

Common sense?

>> You mean I have that much influence on designers of C/C++ software
> 
> If you are designing C/C++ software, then I hope so.
> 
> I disagree with your argument that in Ada one can have separate *.adb files for different platforms, whereas in C++ one uses #ifdefs. This is just wrong.

Once I reviewed C code which had everything in a single header file. Why 
not? It is quite logical if following your logic...

>> You are asking religious questions, why people keep on doing bad things?
> 
> (Lack of) Education might be the answer.
> 
> But note that lack of education is also the reason for people to stay unaware of Ada. So we have a choice: educate people to write good C++ or educate people to write Ada.

It is no choice, because the worse a language is less efficient 
education becomes. Resources of brain are limited. Each language 
irregularity, unsafe choice etc plays against us.

> But choice is a burden. Right? :-)

Absolutely! Since Google, Facebook et all are already at doing 
censorship and suppressing freedom of speech, they could to do a great 
service to the humankind by eradicating "hate" code written in 
"offensive" [programming] languages... (:-))

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

Re: Why .ads as well as .adb?

[G. B.]

Dmitry A. Kazakov <mailbox@dmitry-kazakov.de> wrote:
> On 2019-06-05 11:04, Maciej Sobczak wrote:
>>>> So what exactly cannot be deduced?
>>> 
>>> The class.
>> 
>> What if I don't need the virtual "class" and I'm interested in the
>> single instance only? The one that I wrote?
>> I'd argue this is the most frequent case.
> 
> Would you never wanted to change anything? 

Changes are opportunities for generating business. If the customer is known
to pay for changes, then if the program text is both mathematically
satisfying and easy to maintain, changing it is done quickly. Therefore,
such programs generate small business at best, at least when the customers
know what the changes were. Otherwise, work can be made to look much. So,
the question becomes this: Can the mode of expression of a programming
culture be tuned to that sweet spot between program text satisfying
programmers on the one hand and programs that generate loads of work that
is caused by poor quality?

The mode of expression, then, needs to be studied and compared in real
world workshops that win and loose.

Re: Why .ads as well as .adb?

[Optikos]

On Wednesday, June 5, 2019 at 12:12:36 PM UTC-5, G. B. wrote:
> Dmitry A. Kazakov wrote:
> > On 2019-06-05 11:04, Maciej Sobczak wrote:
> >>>> So what exactly cannot be deduced?
> >>> 
> >>> The class.
> >> 
> >> What if I don't need the virtual "class" and I'm interested in the
> >> single instance only? The one that I wrote?
> >> I'd argue this is the most frequent case.
> > 
> > Would you never wanted to change anything? 
> 
> Changes are opportunities for generating business. If the customer is known
> to pay for changes, then if the program text is both mathematically
> satisfying and easy to maintain, changing it is done quickly. Therefore,
> such programs generate small business at best, at least when the customers
> know what the changes were. Otherwise, work can be made to look much. So,
> the question becomes this: Can the mode of expression of a programming
> culture be tuned to that sweet spot between program text satisfying
> programmers on the one hand and programs that generate loads of work that
> is caused by poor quality?
> 
> The mode of expression, then, needs to be studied and compared in real
> world workshops that win and loose.

This.  Ada was designed (from an incomplete 1970s understanding) to partially dismantle this vicious-cycle mentality of programmers' tail wagging the business's dog and vice versa.  A true solution to this problem that G.B. wisely elucidates will be an extrapolation of the Ada vision that begets a fundamental change to the business model of surviving software companies, while the inferior software companies die off.  Perhaps the focus should shift from 1) merely an incrementally better Ada to 2) Ada-on-steroids that makes current Ada look like an antique, i.e., what if the HOLWG had never stopped?  What if a never-ending HOLWG had behaved all these decades more like the WiFi and USB working groups that pursue aggressive exponential improvement instead of Ada's sublinear incremental improvement?

Ada standardization efforts (and even SPARK's ability to model pointers) are awesome advances, but to be honest they are awesome achievements because the bar throughout the industry is set so low:  in the land of the blind, the one-eyed man can easily rise to be the king.  Think exponentially, not incrementally.

Re: Why .ads as well as .adb?

[Randy Brukardt]

"Optikos" writes:
...
>Ada standardization efforts (and even SPARK's ability to model pointers)
>are awesome advances, but to be honest they are awesome achievements
>because the bar throughout the industry is set so low:  in the land of the
>blind, the one-eyed man can easily rise to be the king.  Think 
>exponentially,
>not incrementally.

This is a good point. Part of the reason that Ada isn't used more is because 
while it is better than other choices, it is not that much better. Inertia 
is an important part of life. Indeed, I don't upgrade/replace much desktop 
software anymore since it is more of hinderance to work (because of things 
changed/removed) than a benefit (new features that I'm unlikely to use). [My 
primary programming editor was last updated in 1986!] That's certainly the 
case for practitioners in other languages as well.

If one really wants to make a splash, one would have to come up with 
something much better. Personally, I don't think that is possible for a 
conventional programming language - at some point, text itself becomes the 
limitation. (But I don't have a clue what that next step should be, 
graphical systems have mostly failed, both for expressivity and usability. 
Probably not programming at all is the next step, which renders all of us 
irrelevant.)

                                          Randy.

Re: Why .ads as well as .adb?

[Randy Brukardt]

"Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
news:f37f6f75-62d4-4152-917e-d666d67f6cb7@googlegroups.com...
...
>> The gain is definition of the scope. C++ equivalent, which I would force
>> in each C++ programming guideline, would be:
>>
>>     {
>>        ... // Some code
>>        {
>>           int X;
>>           X = 1;
>>           ..
>>        }
>>        .. // Some code
>>     }
>
>This is useful if there is a reason to not have X in the second "Some code" 
>part.
>Especially if X is handling some resource. Otherwise there is no gain.
>Still (in both variants), C++ is more readable (the proportion of useful 
>code to
>the whole is higher).

There's a lot more to readability than just the "proportion of useful code". 
Indeed, it is rather important that delimiters be clear and not get lost in 
the code. That's the main fault of C family syntax, critical closings get 
lost (as it is a single skinny character, barely noticiable in most fonts); 
it's hard to tell the difference between that and a blank line in the above. 
(Remember that "some code" is likely to be a fairly large block with more {} 
of it's own.) And C-family code with } on separate lines is a rarity -- most 
of it is all smushed together (more like we'd write parens in Ada).

Ada strikes the critical balance between readability and consiseness. And it 
pretty much is the only language where the language designers truly cared 
about readability (not just in the syntax, but also in how the semantics 
impacts readability), and designed the syntax with readability in mind. Most 
language designers only pay a small amount of attention to readability and 
just design the syntax as a vessel for their semantics. And the results show 
it.

Indeed, the reason to choose Ada is the synergy between the syntax and 
semantics. An conglomeration would not work as well: Ada syntax and C++ 
semantics, or C++ syntax and Ada semantics would both be substantially less 
readable than Ada is.

Ada's syntax is not perfect, of course, but it is as close as has been 
designed to date (at least of the many languages I know about). Particularly 
the original Ada 83 part (I don't think we've always managed to add new 
features in the best possible way).

                                           Randy.

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> There's a lot more to readability than just the "proportion of useful code".

OK, so I'll keep playing the devil's advocate. :-)

> Indeed, it is rather important that delimiters be clear and not get lost in 
> the code.

It's also important for the code not to get lost in delimiters. LISP and Ada are examples of languages where delimiters are distracting and thus cross the fine border between "visible" and "obstructing".

> (as it is a single skinny character, barely noticiable in most fonts);

Please use good fonts. There is absolutely no reason to use bad fonts for doing professional work.
And no, I don't get the argument that the language syntax has the purpose of solving the problem of bad fonts in someone's text editor. On the contrary.

> it's hard to tell the difference between that and a blank line in the above.

This is augmented with the indentation. It's very clear without being obstructing.

> And C-family code with } on separate lines is a rarity

Not in my world. Actually, this is the only style I happen to work with. This style is promoted by all industrial coding standards (both C and C++ language standards examples, MISRA-C, JSF, HICPP, AUTOSAR, ...), so I don't get the argument about "rarity".

Actually, I don't even know where to find something different.

> most 
> of it is all smushed together (more like we'd write parens in Ada).

I don't know where "most" comes from in your statistics.

> Ada strikes the critical balance between readability and consiseness.

Not in the perception of those who attempt to learn it. Ada has the reputation of being overly verbose and considering that such reputation comes from beginners after the initial contact with the language, it very likely comes exactly from the block delimiters.

> And it 
> pretty much is the only language where the language designers truly cared 
> about readability

This statement is unfounded and the word "truly" is dangerous.

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[J-P. Rosen]

Le 05/06/2019 à 10:28, Maciej Sobczak a écrit :
>> Ada strikes the critical balance between readability and
>> consiseness.
> Not in the perception of those who attempt to learn it. Ada has the
> reputation of being overly verbose and considering that such
> reputation comes from beginners after the initial contact with the
> language, it very likely comes exactly from the block delimiters.
> 

Yes, Ada favors readability over writability. Beginners who start typing
and never had to maintain something written a long time ago view this as
a defect.

Ada is for serious, long term engineering. The opinion of beginners is
less important than the opinion of long term maintainers.

But (sigh) this has to be explained over and over again...

-- 
J-P. Rosen
Adalog
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
http://www.adalog.fr

Re: Why .ads as well as .adb?

[Paul Rubin]

"J-P. Rosen" <rosen@adalog.fr> writes:
> Yes, Ada favors readability over writability.

I find when trying to study a codebase, having the code spread across
too many files seriously impairs readability.  That problem is worst
with Java, which puts each class (even small ones) in a separate file.

ML also does have a separate specification languate (the "module
language") and implementation language, I mean really, not like the
crappy .h system of C++.  But I think it is ok (i.e. acceptable though
not universal practice in ML) to put both the interface spec and the
implementation in the same file.  I don't see what is wrong with the
idea of doing the same thing in Ada.

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-05 12:28 , Paul Rubin wrote:
> "J-P. Rosen" <rosen@adalog.fr> writes:
>> Yes, Ada favors readability over writability.
>
> I find when trying to study a codebase, having the code spread across
> too many files seriously impairs readability.  That problem is worst
> with Java, which puts each class (even small ones) in a separate file.

On the other hand, I like it that I can get a first impression of an Ada 
program by reading just the .ads files.

> ML also does have a separate specification languate (the "module
> language") and implementation language, I mean really, not like the
> crappy .h system of C++.  But I think it is ok (i.e. acceptable though
> not universal practice in ML) to put both the interface spec and the
> implementation in the same file.  I don't see what is wrong with the
> idea of doing the same thing in Ada.

Apart from all the other reasons already given, keeping spec and body in 
the same file can cause compilation-order problems. Suppose that there 
are two packages, A and B, such that the specs do not depend on each 
other but the bodies do. That is, the body of A has "with B" (which 
really means, "with the spec of B") and the body of B has "with A" 
(which really means, "with the spec of A"). If the spec and body of A 
are both in one and the same file, and the spec and body of B are both 
in another file, when the compiler processes a "with" clause it would 
have to be able to read, parse and use only the spec part of the 
"withed" file, while ignoring the body part (because it depends on a 
spec not yet seen).

I admit that this kind of mutual dependence between packages is often 
frowned on (because it breaks architectural "layering") but I find it 
hard to completely avoid it.

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

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> On the other hand, I like it that I can get a first impression of an Ada 
> program by reading just the .ads files.

This. This is important.
I have seen the suggestion to treat spec files as a low-level requirements document, to be completed by the body. This is a convincing argument for keeping these files separate.

But on the other hand, there are coding patterns that achieve the same effect without distinguishing between spec and implementation. The interface design pattern does it, for example. This is exactly how Java programmers achieve decoupling - but note that this is a voluntary action, so can be also limited to only those places where it is actually needed.

Say, I need this idiom in 10% of packages. Why am I penalized in the remaining 90% and forced to write specs that are demonstrably not needed?

In particular, it is very difficult to explain this concept to beginners, because in simple examples the redundancy of syntax is just shocking - the package spec looks like copy-paste of signatures; and arguably this is how some of the specs are born in practice. The language that forces me to copy-paste stuff between files is not inviting me to study it more deeply.

What we are discussing is whether this copy-pasting has added values that justify the costs.

> Apart from all the other reasons already given, keeping spec and body in 
> the same file can cause compilation-order problems.

Only if you assume that the compiler reads the file only once and therefore must validate everything in a single pass.

Which is not the case anyway, not even in Ada (nor in C++). That's why this concept looks a bit archaic today.

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-05 15:58 , Maciej Sobczak wrote:
>> On the other hand, I like it that I can get a first impression of
>> an Ada program by reading just the .ads files.
>
> This. This is important. I have seen the suggestion to treat spec
> files as a low-level requirements document, to be completed by the
> body.

I imagine that is how most Ada programmers design programs -- divide the 
thing into packages, write the specs for each package to document the 
division of responsibilities and functions, and then implement the 
bodies according to the specs. (Of course this means that the .ads files 
should contain lots of requirements written as comments or contracts.)

In the SW processes used in ESA projects, these steps are often 
separated into successive phases: architectural design first, detailed 
design+coding second, with the two phases separated by a formal review 
meeting.

> In particular, it is very difficult to explain this concept to
> beginners, because in simple examples the redundancy of syntax is
> just shocking - the package spec looks like copy-paste of signatures;

The "redundancy" applies only to subprograms, and is in fact not 
redundant once overloading is used.

Most of my specs contain mostly type declarations, with a smattering of 
subprogram declarations -- no, in fact most of my specs contain mostly 
comments to explain the types and to specify and explain what the 
subprograms (should) do. Most subprograms in the bodies are private and 
are not declared in the spec.

 > and arguably this is how some of the specs are born in practice.

Usually the body is initialized as a copy of the relevant parts of the 
spec. GPS even has a menu command for this, which generates an .adb 
file, with null subprogram bodies, from an .ads file.

I copy declarations from body to spec only if I find, while implementing 
the program, that I must publish something that I originally did not 
intend to make visible to clients.

> The language that forces me to copy-paste stuff between files is not
> inviting me to study it more deeply.

Hmm. The same copy-paste applies to C (header files vs .c files).

>> Apart from all the other reasons already given, keeping spec and
>> body in the same file can cause compilation-order problems.
>
> Only if you assume that the compiler reads the file only once and
> therefore must validate everything in a single pass.

No, the compiler does not *have* to validate everything at once, but 
mixing .ads and .adb in the same file means (as I said) that the 
compiler must have the ability to avoid validating the .adb part if it 
is only "withing" the file. This makes the compiler more complex, 
although the fact that Ada (unlike some other languages) does not allow 
application-defined syntax extensions (such as macros) would keep it 
tractable.

> Which is not the case anyway, not even in Ada

Explain why an Ada compiler should have to read a source file multiple 
times, please. GNAT does it (for .ads files and in some other cases) but 
some compilers do not, AFAIK.

If your point is only that most present-day compilers are (internally) 
multi-pass, that is true, but I don't see the relevance.

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

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> Usually the body is initialized as a copy of the relevant parts of the 
> spec. GPS even has a menu command for this, which generates an .adb 
> file, with null subprogram bodies, from an .ads file.

Isn't it a proof that tools are trying to fix the language problem?

> Hmm. The same copy-paste applies to C (header files vs .c files).

I have never said C is any better in this regard.

The discussion started with the observation that some languages manage not to have this separation at all. So we are not comparing Ada to C (superiority of bracketing styles being another subthread), we are comparing Ada/C with say Java or Python.

> If your point is only that most present-day compilers are (internally) 
> multi-pass, that is true, but I don't see the relevance.

The relevance is that the argument about the difficulty the compiler might have when parsing interdependent files that have no separate specs is now not relevant. :-)

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[Keith Thompson]

Maciej Sobczak <see.my.homepage@gmail.com> writes:
>> Usually the body is initialized as a copy of the relevant parts of the 
>> spec. GPS even has a menu command for this, which generates an .adb 
>> file, with null subprogram bodies, from an .ads file.
>
> Isn't it a proof that tools are trying to fix the language problem?

Not at all.  It's evidence that some users find such as tool useful.

Other users, I suspect most of them, wouldn't use that particular
feature, since they'd prefer to write the .ads and .adb as separate
files in the first place.

For example, I might write the .ads file first, then copy it to
the .adb file and edit it (since a lot of the text is duplicated).

A lot of people *prefer* having separate .ads and .adb files.

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[J-P. Rosen]

Le 06/06/2019 à 21:51, Keith Thompson a écrit :
> A lot of people *prefer* having separate .ads and .adb files.
This has been recommended practice ever since Ada 83.
The reason is that otherwise, every time you fix a detail in the body,
you recompile the spec at the same time, making every unit that depends
on the spec obsolete.

-- 
J-P. Rosen
Adalog
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
http://www.adalog.fr

Re: Why .ads as well as .adb?

[Randy Brukardt]

"Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
news:4a0438de-1f1d-4469-aae4-908854d378ea@googlegroups.com...
>> Usually the body is initialized as a copy of the relevant parts of the
>> spec. GPS even has a menu command for this, which generates an .adb
>> file, with null subprogram bodies, from an .ads file.
>
> Isn't it a proof that tools are trying to fix the language problem?

An IDE for a language that doesn't separate a spec certainly needs to have a 
mode where you could only see the specification parts of a source unit. That 
certainly is proof of tools fixing a language problem. ;-)

Ergo, no language is going to be perfect; language design is a series of 
trade-offs, and one imagines that tools will fix things up for people that 
would rather have a different trade-off.

                                                    Randy.

Re: Why .ads as well as .adb?

[Randy Brukardt]

"Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
news:4a0438de-1f1d-4469-aae4-908854d378ea@googlegroups.com...
...
>>> If your point is only that most present-day compilers are (internally)
>>> multi-pass, that is true, but I don't see the relevance.
>>
>> The relevance is that the argument about the difficulty the compiler 
>> might
>have when parsing interdependent files that have no separate specs is now
>not relevant. :-)

The difficulty of a compiler never was very relevant (it's *waaay* down a 
list of requirements). Of course, you are essentially saying that separate 
compilation is unnecessary and all of the source for a program should be in 
one giant file (it's certainly easier to edit and find things that way).

But of course that is nonsense, because of the value of compiling incomplete 
programs, the value of binary-only distributions, the value of separate 
programmers/teams working on carefully separated parts, and the value of 
reduced coupling.

                                             Randy.

Re: Why .ads as well as .adb?

[Dennis Lee Bieber]

On Thu, 6 Jun 2019 16:17:37 -0500, "Randy Brukardt" <randy@rrsoftware.com>
declaimed the following:


>The difficulty of a compiler never was very relevant (it's *waaay* down a 
>list of requirements). Of course, you are essentially saying that separate 
>compilation is unnecessary and all of the source for a program should be in 
>one giant file (it's certainly easier to edit and find things that way).
>

	Visions of my college days -- Xerox Sigma 6 CP/V Extended FORTRAN IV.
We weren't even introduced to the concept of separate files (neither did
the COBOL class).

	Of course, the first FORTRAN compiler we were introduced to was FLAG
(FORTRAN Load And Go -- compile one source file, link it, and execute it
all in one operation). The single source file mode did make for long
listings of code, but simplified the linker pass: FORT <source>; LINK
<object>; <executable>


-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
	wlfraed@ix.netcom.com    http://wlfraed.microdiversity.freeddns.org/

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> Of course, you are essentially saying that separate 
> compilation is unnecessary and all of the source for a program should be in 
> one giant file

Of course you are proving now that you did not understand the question posted earlier in this thread.

1. There *are* languages that don't use separate spec files. Java and Python are well known examples, representing both compiled and scripted approaches.

2. Programs written in those languages do *not* need to be written in one giant file. Actually, Java is frequently criticized (it was even in this thread) for forcing the programmer to use too many (!) files. Even though it does not have separate specs.

Obviously, I'm *not* saying that separate compilation units are not needed and I'm *not* saying that programs should be written in one giant file.

What I'm saying is that experiences gathered with other languages allow to question some of the reasons that are frequently cited as a justification for having separate spec files.

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[alby.gamper]

On Friday, June 7, 2019 at 5:59:26 PM UTC+10, Maciej Sobczak wrote:
> > Of course, you are essentially saying that separate 
> > compilation is unnecessary and all of the source for a program should be in 
> > one giant file
> 
> Of course you are proving now that you did not understand the question posted earlier in this thread.
> 
> 1. There *are* languages that don't use separate spec files. Java and Python are well known examples, representing both compiled and scripted approaches.

Both Java and Python are interpretive languages and can/do pre-compile to their
native VM byte code as an optimization for their respective VM's to run. Neither
language is truly compiled to native machine form as I understand it!

> 
> 2. Programs written in those languages do *not* need to be written in one giant file. Actually, Java is frequently criticized (it was even in this thread) for forcing the programmer to use too many (!) files. Even though it does not have separate specs.
> 
> Obviously, I'm *not* saying that separate compilation units are not needed and I'm *not* saying that programs should be written in one giant file.
> 
> What I'm saying is that experiences gathered with other languages allow to question some of the reasons that are frequently cited as a justification for having separate spec files.

At a high level :-)

If you think of an Ada Specification file (ie ads) as being semi equivalent to
an interface specification in other languages such as C#, C/C++, IDL, and the
Implementation (ie adb) to a separate file then it may make sense. Look at the proliferation of source files that specify one or more C# interfaces in the
MS Roslyn project and their separate implementation in other files. Although C#
doesn't enforce the separation, it is common a (engineering, industry) practice
within the C# and C/C++ space to do so.

> 
> -- 
> Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[Dennis Lee Bieber]

On Fri, 7 Jun 2019 03:42:25 -0700 (PDT), alby.gamper@gmail.com declaimed
the following:

>Both Java and Python are interpretive languages and can/do pre-compile to their
>native VM byte code as an optimization for their respective VM's to run. Neither
>language is truly compiled to native machine form as I understand it!
>
	The Java runtime system has included a JIT compiler for some years now.
But yes -- that is not the "compiler" as most think of it. The invoked
compiler produces byte-code. The JIT compiler proves useful if a program
has sections that are repeatedly executed -- but one-time chunks of code
take the JIT compile time as a penalty which could be more than simple
byte-code interpretation would consume.



-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
	wlfraed@ix.netcom.com    http://wlfraed.microdiversity.freeddns.org/

Re: Why .ads as well as .adb?

[Brad Moore]

On Friday, June 7, 2019 at 1:59:26 AM UTC-6, Maciej Sobczak wrote:
> > Of course, you are essentially saying that separate 
> > compilation is unnecessary and all of the source for a program should be in 
> > one giant file
> 
> Of course you are proving now that you did not understand the question posted earlier in this thread.
> 
> 1. There *are* languages that don't use separate spec files. Java and Python are well known examples, representing both compiled and scripted approaches.

I suspect that may be more to do with language limitations than anything else,
where the compiler needs to "see" all the code to generate the executable.
I think the same could be said of C++ templates, where the template header file contains all the code, so that the compiler can generate the executable when that source code is inserted into another source file via an #include preprocessor directive.

I am not a Java expert, but I note that Java didn't have modules until 2017 in Java 9, but by then Java coding styles were already cemented in through years of usage. Ada had compiled modules and separate compilation in the form of packages since the beginning.

Bolting on features to languages after the fact can be an improvement, but it helps a lot if the language was well designed from the start.

I think it is a big mistake of languages that encourage the specification and implementation to be in the same source file, and very surprised to see that anyone would be arguing for that.

The separation of specification and implementation ties into the "separation of concerns" attributed to Dijkstra way back in 1974.

When wanting to make use of a 3rd party package in Ada, I value being able to generally understand how to use that package by looking at the specification without having to look at the implementation. You generally only need to look at the public part of a package specification, as you can rely on anything past that as being implementation details.

Even with C++, one cannot stop reading when you see a private: keyword in a class definition, because there can be many public and private sections in a class. You have to keep reading the class specification until to hit the end of the class specification, in case you missed more public parts.

I think Ada does a better job of getting the programmer to separate specification from implementation.

This can become really valuable when programming in the large. For this reason, I think Python is not a good choice for developing a very large system.

I see it as a nice language for writing smaller programs, scripts, and glue-code, etc.

I suspect that when teaching programming languages, small examples are provided that demonstrate language features, and packages in Ada are often not needed. For example, if one looks at the Ada examples in the Rosetta code website, 

http://www.rosettacode.org 

You will often see examples that do not use packages. So Ada does seem to provide good capabilities write examples in a single file when that is needed.

When you work on a large system however, you quickly learn to appreciate the separation of specification and implementation however. 

> 
> 2. Programs written in those languages do *not* need to be written in one giant file. Actually, Java is frequently criticized (it was even in this thread) for forcing the programmer to use too many (!) files. Even though it does not have separate specs.

Maybe Ada offers a benefit here. In languages like Java, there is a tendency to want to put each class in a separate file. With Ada packages, it can make more sense to organize related types in the same package.

Brad

Re: Why .ads as well as .adb?

[Paul Rubin]

Brad Moore <bmoore.ada@gmail.com> writes:
> I think it is a big mistake of languages that encourage the
> specification and implementation to be in the same source file, and
> very surprised to see that anyone would be arguing for that.

That seems like saying it's a mistake for math textbooks to be published
as single volumes.  The text should instead be done in 2 volumes, with
the statements of the theorems in the first volume, and the proofs in
the second.  In practice I don't know of any math textbooks published
that way.  There are some multi-volume ones, but they all still go:
theorem, proof, theorem, proof.

Re: Why .ads as well as .adb?

[Brad Moore]

On Friday, June 7, 2019 at 5:37:28 PM UTC-6, Paul Rubin wrote:
> Brad Moore <bmoore.ada@gmail.com> writes:
> > I think it is a big mistake of languages that encourage the
> > specification and implementation to be in the same source file, and
> > very surprised to see that anyone would be arguing for that.

I should clarify that I think it's a mistake (or at least a poor design choice) if the intent is for the language to be used for large scale systems with maintainability as a goal (write once - read many). Ada tries to be general enough for that purpose while also supporting writing in the small,
but some languages are designed for more specific purposes.

If a language is designed to be mainly something used for writing quick and dirty scripts, smaller programs, demos, prototyping, etc where maintainability is less a concern then maybe it makes sense to design the language for conciseness of expression, minimal specifications and perhaps simpler implementation for the compiler.

> 
> That seems like saying it's a mistake for math textbooks to be published
> as single volumes.  The text should instead be done in 2 volumes, with
> the statements of the theorems in the first volume, and the proofs in
> the second.  In practice I don't know of any math textbooks published
> that way.  There are some multi-volume ones, but they all still go:
> theorem, proof, theorem, proof.

The theorems and proofs still sound like they are separate even if together in the same book. The theorems are not interlaced in dribs and drabs amongst the proof. Maybe there are proofs that are organized that way, but I would think that would be the exception rather than the rule.

This feels like another apples and orange comparison, but I think what I am trying to say is more closer to buying a bookshelf from IKEA. The instructions are the interface specifications that tell me how to assemble their product. I don't need to see how they implemented their product. What types of trees were used for the wood, the how the boards were cut, the measurements of the cuts, the diameters, depths, and locations, of the screw holes, the type of veneer that was applied, how the veneer was produced, what type of glue they used to fasten the veneer, how long they let the glue dry, the types of metals used in the screws, and cabinet hardware, how the cabinet hardware was manufactured, etc. While this all might make for an interesting read in my leisure, when I am trying to get the shelf assembled, the last thing I want is to have to read through pages and pages of text to find the next instruction I need to follow. Chances are I'll end up missing an important step lost in the middle, and end up with way too many left over screws in the end, or have to take everything apart and start over.

Brad

Re: Why .ads as well as .adb?

[Simon Wright]

Brad Moore <bmoore.ada@gmail.com> writes:

> The theorems and proofs still sound like they are separate even if
> together in the same book. The theorems are not interlaced in dribs
> and drabs amongst the proof. Maybe there are proofs that are organized
> that way, but I would think that would be the exception rather than
> the rule.

Sounds like my attempts at literate programming:
http://embed-web-srvr.sourceforge.net/ews.pdf

Re: Why .ads as well as .adb?

[G.B.]

On 08.06.19 01:37, Paul Rubin wrote:
> Brad Moore <bmoore.ada@gmail.com> writes:
>> I think it is a big mistake of languages that encourage the
>> specification and implementation to be in the same source file, and
>> very surprised to see that anyone would be arguing for that.
> 
> That seems like saying it's a mistake for math textbooks to be published
> as single volumes.  The text should instead be done in 2 volumes, with
> the statements of the theorems in the first volume, and the proofs in
> the second.  In practice I don't know of any math textbooks published
> that way.  There are some multi-volume ones, but they all still go:
> theorem, proof, theorem, proof.

Another, different comparison can see a spec as a list
of definitions to be dwelt on later in the text.

Re: Why .ads as well as .adb?

[Keith Thompson]

Paul Rubin <no.email@nospam.invalid> writes:
> Brad Moore <bmoore.ada@gmail.com> writes:
>> I think it is a big mistake of languages that encourage the
>> specification and implementation to be in the same source file, and
>> very surprised to see that anyone would be arguing for that.
>
> That seems like saying it's a mistake for math textbooks to be published
> as single volumes.  The text should instead be done in 2 volumes, with
> the statements of the theorems in the first volume, and the proofs in
> the second.  In practice I don't know of any math textbooks published
> that way.  There are some multi-volume ones, but they all still go:
> theorem, proof, theorem, proof.

Math textbooks have a table of contents and an index.  Both *could* be
in separate volumes, but there would be no particular advantage in that
(though it's entirely possible that the author kept them in separate
files).

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[Paul Rubin]

Keith Thompson <kst-u@mib.org> writes:
> Math textbooks have a table of contents and an index.  Both *could* be
> in separate volumes, but there would be no particular advantage in that
> (though it's entirely possible that the author kept them in separate
> files).

Sure, that's a good comparison.  Actually typically, the TOC and index
are generated by software using inline markers that the author puts in
the text.  There might be an occasional situation where you want the TOC
and the main text to be in separate volumes (like for a 100 volume
series you could want a special volume just for the TOC), but normally
it's fine to print both in the same volume.

So it still seems annoying to requires the spec and body to be in
separate files.

Also in Java, I thought that top level class definitions were required
to be in separate files.  At least I've always seen it done that way,
and it makes it much harder to browse the code IME.  I like file sizes
that are small enough to conveniently browse but that have enough
content to keep me occupied without having to switch around between
files.  In practice that means maybe 10 to 30 screens, depending.

Re: Why .ads as well as .adb?

[Keith Thompson]

Paul Rubin <no.email@nospam.invalid> writes:
> Keith Thompson <kst-u@mib.org> writes:
>> Math textbooks have a table of contents and an index.  Both *could* be
>> in separate volumes, but there would be no particular advantage in that
>> (though it's entirely possible that the author kept them in separate
>> files).
>
> Sure, that's a good comparison.  Actually typically, the TOC and index
> are generated by software using inline markers that the author puts in
> the text.  There might be an occasional situation where you want the TOC
> and the main text to be in separate volumes (like for a 100 volume
> series you could want a special volume just for the TOC), but normally
> it's fine to print both in the same volume.

Programs are not books.

> So it still seems annoying to requires the spec and body to be in
> separate files.

Code is read more often than it's written.  As someone reading code
and trying to understand it, I appreciate having the specification
by itself in a separate file, so I can see the information needed
by clients of the code without having to concern myself with the
implementation (which can vary).

How often do you want to read the specification of Text_IO?
How often do you need to read the implementation?

Tools that can generate a specification from a possibly annotated
implementation are fine, but it's inconvenient (and sometimes
impossible) to invoke such a tool every time I want to see the
specification.

[...]

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[John Perry]

(1) Ada's approach has one advantage that I don't remember anyone mentioning (apologies if you did and I missed it or forgot):

I can't remember the number of times I modified a C++ / Eiffel / Java / Oberon / whatever file, and forgot to update the documentation. So now the specification / documentation and the implementation are out of sync, and in my experience nothing is harder to debug than a wrongly documented specification.

In Ada, if you forget to update the specification file, your system probably won't compile. The language thus forces you to update that.

That said...

(2) I've read some very good arguments made in favor of separate specification files, but I don't understand why the conversation keeps coming around to "the specification file provides convenient documentation," or even, "if I want to see the specification from the implementation, I have to run a tool every time I want to see it, and that can be inconvenient." Those aren't just weak arguments; they're plainly false.

When I want to know how Ada.Text_IO works, I don't look up the specification file. I don't even know where to find Ada.Text_IO on my system. I just went to look for it, and gave up pretty quickly. I could probably find it if I tried hard enough, but it's far more convenient to visit [1], which has a hyperlink to Ada.Text_IO, as well as lots of other things.

I imagine that [1] was generated by some software tool. Similar tools exist for other languages. Take a look at [2] to see what a nice job they can do -- a LOT nicer than [1]. If I click on BINARY_SEARCH_TREE, not only do I get the specification for BINARY_SEARCH_TREE a la [1], but I also get links to related specifications, such as COMPARABLE, TREE_ITERATION_CURSOR, and so forth. This is much, _much_ more helpful than the specification file by itself.

Some have suggested that the markup required to do this can make the source file unreadable. Eiffel's source files are some of the most readable I've ever encountered, certainly no less readable than Ada (IMHO). Doxygen and javadoc markup aren't especially painful to read, either, and they do much the same thing.

Moreover, there's no need to invoke such a tool every time you want to see the specification, and thus no inconvenience at all. You generate the specification / documentation once and it ends up in a file that you can distribute just as easily as an .ads. The only time one has to invoke Doxygen, javadoc, etc. is if the exported objects change.

The downside is that you *have* to remember to update the documentation -- something I usually do remember, but not always. That's what made me think that Ada's approach does offer an advantage here (see above).

[1] http://www.ada-auth.org/standards/12rm/html/RM-TOC.html
[2] https://www.eiffel.org/files/doc/static/19.05/libraries/base/index.html

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-09 23:35 , John Perry wrote:
>  ...
> (2) I've read some very good arguments made in favor of separate
> specification files, but I don't understand why the conversation
> keeps coming around to "the specification file provides convenient
> documentation," or even, "if I want to see the specification from the
> implementation, I have to run a tool every time I want to see it, and
> that can be inconvenient." Those aren't just weak arguments; they're
> plainly false.
>
> When I want to know how Ada.Text_IO works, I don't look up the
> specification file.

I do, about half the time (the rest of the time I look it up in the RM).

> I don't even know where to find Ada.Text_IO on my
> system.

Your IDE (GPS) knows. And its not hard to find, either, once you figure 
out its file-name (with gnatkr).

> ... it's far more
> convenient to visit [1], which has a hyperlink to Ada.Text_IO, as
> well as lots of other things.

Sure the RM is often convenient, but it shows only the standard 
packages. Most of the packages in a non-trivial application will be 
application-specific.

> I imagine that [1] was generated by some software tool.

AIUI it was generated, but not from an Ada spec (.ads) file.

> Similar tools
> exist for other languages. Take a look at [2] to see what a nice job
> they can do -- a LOT nicer than [1].

Matter of opinion.

> If I click on
> BINARY_SEARCH_TREE, not only do I get the specification for
> BINARY_SEARCH_TREE a la [1], but I also get links to related
> specifications, such as COMPARABLE, TREE_ITERATION_CURSOR, and so
> forth. This is much, _much_ more helpful than the specification file
> by itself.

A good IDE will give you the same links.

> Some have suggested that the markup required to do this can make the
> source file unreadable.

The markup makes the file less readable, IMO. No markup is really 
required for getting nice views and cross-links -- it is enough to 
follow some simple conventions for locating descriptions (comments) 
close to the declarations they describe.

> Doxygen and javadoc markup aren't especially painful to read,
> either, and they do much the same thing.

I find them a little painful, though.

> Moreover, there's no need to invoke such a tool every time you want
> to see the specification, and thus no inconvenience at all.

While a program is being built, the specs of that program's specific 
packages change often, unlike the spec of standard packages like Text_IO.

> You
> generate the specification / documentation once and it ends up in a
> file that you can distribute just as easily as an .ads.





  The only time
> one has to invoke Doxygen, javadoc, etc. is if the exported objects
> change.
>
> The downside is that you *have* to remember to update the
> documentation -- something I usually do remember, but not always.
> That's what made me think that Ada's approach does offer an advantage
> here (see above).
>
> [1] http://www.ada-auth.org/standards/12rm/html/RM-TOC.html [2]
> https://www.eiffel.org/files/doc/static/19.05/libraries/base/index.html
>
>
-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
       .      @       .

Re: Why .ads as well as .adb?

[John Perry]

Hi Niklas

Let me preface my reply by saying that I think we mostly agree.

On Sunday, June 9, 2019 at 4:15:37 PM UTC-5, Niklas Holsti wrote:
> > I don't even know where to find Ada.Text_IO on my
> > system.
> 
> Your IDE (GPS) knows. And its not hard to find, either, once you figure 
> out its file-name (with gnatkr).

Sure, but such an IDE has to be Ada-ready, and in any case turns one of the arguments I was complaining about on its head: you have to use a special tool for it, and in this case you really *do* have to use the special tool every time you want to look something up. The Eiffel documentation I pointed to, like the ADA RM, doesn't require anything more than a web browser.

You refer to GPS. GPS does not come with FSF gnat, at least not on my Linux distribution (Fedora), not as far as I know. For the first couple of years I toyed with Ada, that's what I had. Also, I never heard of gnatkr before reading this, and it doesn't seem to have a man file on any of my systems. I do however appreciate learning this!

[Now that I'm getting more serious, I've downloaded the CE edition & AdaCore has been really nice with some help (I'm an academic), so I should probably acknowledge that.]

> AIUI it was generated, but not from an Ada spec (.ads) file.

I would like to know how that was generated. I figured the spec was the easiest way to do it. A lot of the documentation in the RM is really thorough -- a bit intimidating in its thoroughness, in fact.

> > Some have suggested that the markup required to do this can make the
> > source file unreadable.
> 
> The markup makes the file less readable, IMO. No markup is really 
> required for getting nice views and cross-links -- it is enough to 
> follow some simple conventions for locating descriptions (comments) 
> close to the declarations they describe.

I agree with the second part, but since all the markup I've seen for Doxygen and javadoc appear in comments, I don't really understand the first. It's an opinion, so I can't really complain, but I do wish to express my dissent. :-)

> > Moreover, there's no need to invoke such a tool every time you want
> > to see the specification, and thus no inconvenience at all.
> 
> While a program is being built, the specs of that program's specific 
> packages change often, unlike the spec of standard packages like Text_IO.

Fair enough, but a lot of the conversation previously had revolved around different teams in different locations, and my impression from the conversation was that those specs were fairly stable. That was the context I had in mind, but I agree with what you say, if only from painful experience.

> Typically [Doxygen-generated spec] is as useless as the "User Manuals" for GUIs that just show screen-shots of various dialogs and explain things like "to frobnicate the lesneric, press the <Frobnicate the Lesneric> button -- without any coherent description of "frobnication" or "lesnerics". 

Of course. I think I deleted from my earlier message a brief rant on how I once tried to figure out an Android service and ended up fighting (1) terribly written documentation, (2) non-working sample code, and (3) a Google developer's Google+ help page that featured soft porn (I swear I am not making any of this up). In the end I had spent 8 hours trying to figure out why my code wouldn't work, simple because Google's documentation told you to use version X, while the sample code used version Y, and for whatever reason I actually had to use version Z. (The fact that the sample code didn't work was actually part of what clued me in to the problem.)

So I am absolutely nodding as I read what you're saying there. But, that's more a problem with the writer of the documentation, the culture of the software development outfit, etc. We're supposed to be talking about a language and/or documentation issue.

If you want to argue that Ada's approach to separating spec and implementation forces the programmer to write better documentation than you'd get from Doxygen, javadoc, etc., you're welcome to make that argument. Some people have hinted in that direction, but I haven't seen anything really convincing. I think it much more likely that if Ada's users are generally more careful with documentation, then that has a lot to do with their target applications: if an Android app crashes, who cares? but if a Boeing falls out of the sky, that's a problem.

As far as I can tell, this has nothing at all to do with having two files versus having one file, and that's my point. So we seem to be in agreement, since as you point out:

> But of course this can  be automated -- it is IMO _not_ the main problem with Doxygen-type documentation, and this is anyway not relevant to the subject of this thread: why Ada separates specifications from implementations.

Right. My quarrel, which is really more of an irritation, is with those whose arguments suggest they think it's impossible to generate specification / documentation from an implementation file, and that seems to keep coming up, so I just wanted to put a quick word in about it. That's all. It has no bearing at all with the great answers provided by others, and for which I'm grateful.

Re: Why .ads as well as .adb?

[Simon Wright]

John Perry <john.perry@usm.edu> writes:

>> AIUI it was generated, but not from an Ada spec (.ads) file.
>
> I would like to know how that was generated. I figured the spec was
> the easiest way to do it. A lot of the documentation in the RM is
> really thorough -- a bit intimidating in its thoroughness, in fact.

See the home of the ARM[1] - scroll down to the second heading, "Ada
Reference Manual Source Files". If you're interested, I'd download the
zip archive - the VCS used appears to be CVS. (Would be better ion
Github, IMO)

It's a requirements manual for what an Ada compiler must do (and, of
course, must not do) so things do have to be spelt out!

There isn't an authoritative user-oriented manual; the Rationale[2] says
why things are the way they are. There are learning materials listed[3].

[1] http://www.ada-auth.org/arm.html
[2] http://www.ada-auth.org/standards/rationale12.html

Re: Why .ads as well as .adb?

[Simon Wright]

Simon Wright <simon@pushface.org> writes:

> There are learning materials listed[3].

[3] https://www.adaic.org/learn/materials/

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-10 01:37 , John Perry wrote:
> Hi Niklas
>
> Let me preface my reply by saying that I think we mostly agree.

Very likely!

> On Sunday, June 9, 2019 at 4:15:37 PM UTC-5, Niklas Holsti wrote:
>>> I don't even know where to find Ada.Text_IO on my system.
>>
>> Your IDE (GPS) knows. And its not hard to find, either, once you
>> figure out its file-name (with gnatkr).
>
> Sure, but such an IDE has to be Ada-ready, and in any case turns one
> of the arguments I was complaining about on its head: you have to use
> a special tool for it, and in this case you really *do* have to use
> the special tool every time you want to look something up.

Programmers nowadays mostly work with an IDE, so I don't see the IDE as 
a "special tool", but as the tool that one uses all day long.

> You refer to GPS. GPS does not come with FSF gnat, at least not on my
> Linux distribution (Fedora), not as far as I know.

I believe it is available in the GNAT Community Edition and should work 
with the FSF compiler. There is also an Ada-mode for Emacs, but I don't 
know how that works as I've never used it.

> For the first
> couple of years I toyed with Ada, that's what I had. Also, I never
> heard of gnatkr before reading this, and it doesn't seem to have a
> man file on any of my systems. I do however appreciate learning
> this!

Sorry if I was being opaque. For (I assume) deep historical reasons the 
source-code files of the GNAT Ada libraries and run-times have 
abbreviated names, not following the normal GNAT file-naming 
conventions. gnatkr is an AdaCore tool, provided with GNAT, which 
translates ("krunches") the normal name into its abbreviated form. 
Running "gnatkr ada-text_io.ads" outputs "a-textio.ads", and that is the 
file name GNAT uses for the Ada.Text_IO spec, which is located in an 
"adainclude" folder within the GNAT installation.

> I would like to know how [the RM] was generated. I figured the spec was
> the easiest way to do it. A lot of the documentation in the RM is
> really thorough -- a bit intimidating in its thoroughness, in fact.

Randy Brukardt is the man to answer questions on the generation of the 
RM -- I don't know much more than I've said, sorry.

>>> Some have suggested that the markup required to do this can make
>>> the source file unreadable.
>>
>> The markup makes the file less readable, IMO. No markup is really
>> required for getting nice views and cross-links -- it is enough to
>>  follow some simple conventions for locating descriptions
>> (comments) close to the declarations they describe.
>
> I agree with the second part, but since all the markup I've seen for
> Doxygen and javadoc appear in comments, I don't really understand the
> first. It's an opinion, so I can't really complain, but I do wish to
> express my dissent. :-)

For example, I write enumeration type declarations as follows:

    type Hue_T
    --
    -- The colour shade of something.
    --
    is (

       Red,
       -- Longest wavelength.

       Green,
       -- Middling long wavelengths.

       Blue
       -- Shortest wavelength.

       );

GPS is then smart enough to associate the comment "The colour shade of 
something" with Hue_T, to associate each of the comments on the three 
literals with that specific literal, and to pop up the comment when I 
point (hover) at an occurrence of the type identifier or the literal. 
Without any annotation markers in the comments.

Before I became a GPS user, I used to declare enumerations in this style:

    type Hue_T is (
       Red,
       Green,
       Blue);
    --
    -- The colour shade of something.
    --   Red   Longest wavelength.
    --   Green Middling long wavelengths.
    --   Blue  Shortest wavelength.

This was more compact (we had those 24-row by 80-column screens back 
then...) but would require some markup to associate literal names 
("Red") with their descriptions. I now consider the first form better, 
because it has less duplication, is more scalable (to larger numbers of 
literals), and because of the connections it supplies to GPS and other 
tools that connect descriptive comments with the "describees".

>>> Moreover, there's no need to invoke such a tool every time you
>>> want to see the specification, and thus no inconvenience at all.
>>
>> While a program is being built, the specs of that program's
>> specific packages change often, unlike the spec of standard
>> packages like Text_IO.
>
> Fair enough, but a lot of the conversation previously had revolved
> around different teams in different locations, and my impression from
> the conversation was that those specs were fairly stable. That was
> the context I had in mind, but I agree with what you say, if only
> from painful experience.

In an ideal world, the specs are stable, once written and published to 
the team. But, as we agree, the world is seldom ideal... Anyway, I think 
we also agree that even if a tool is required to generate the 
documentation, that can easily be automated -- say, a script that is 
executed on every version-control commit.

>> Typically [Doxygen-generated spec] is as useless as the "User
>> Manuals" for GUIs that just show screen-shots of various dialogs
>> and explain things like "to frobnicate the lesneric, press the
>> <Frobnicate the Lesneric> button -- without any coherent
>> description of "frobnication" or "lesnerics".
>
> Of course. I think I deleted from my earlier message a brief rant on
> how I once tried to figure out an Android service and ended up
> fighting (1) terribly written documentation, (2) non-working sample
> code, and (3) a Google developer's Google+ help page that featured
> soft porn (I swear I am not making any of this up).

Wow.

> In the end I had
> spent 8 hours trying to figure out why my code wouldn't work, simple
> because Google's documentation told you to use version X, while the
> sample code used version Y, and for whatever reason I actually had to
> use version Z. (The fact that the sample code didn't work was
> actually part of what clued me in to the problem.)
>
> So I am absolutely nodding as I read what you're saying there. But,
> that's more a problem with the writer of the documentation, the
> culture of the software development outfit, etc.

Yes, definitely. Nothing forces a programmer to write comments -- well, 
nothing except coding rules and metrics rules and checks of those rules.

Alluding to one of my earlier posts, where I complained about how some 
static-analysis tools compute their comment-to-code metrics, another 
weird thing about those metrics is that they seem concerned only with 
executable code, and not with declarations. I find that if an Ada 
program's types are well described (with comments), the subprograms need 
much less description, but I don't remember any static-analysis tool 
that checks the amount of description of declarations.

And of course an automatic check of the _quality_ of the descriptive 
comments is a hard problem (though it might be interesting to try some 
machine-learning methods on it).

Marker-based systems such as Doxygen could make it easier to check the 
presence of descriptions of all required kinds. For example, some coding 
rules require the descriptive comments for a subprogram to contain a 
specific set of paragraphs and statements, such as whether the 
subprogram is "task safe" or has some synchronization requirements. If 
each such item or kind of descriptive information is introduced by a 
specific marker or heading, a static-analysis tool would find it simpler 
to check that all items are present. In my past projects the 
presence-check has been part of a general code inspection/review 
process, supported by manual check-lists.

> We're supposed to be
> talking about a language and/or documentation issue.
>
> If you want to argue that Ada's approach to separating spec and
> implementation forces the programmer to write better documentation
> than you'd get from Doxygen, javadoc, etc., you're welcome to make
> that argument.

Thanks, but I'm not saying quite that. More below.

> Some people have hinted in that direction, but I
> haven't seen anything really convincing. I think it much more likely
> that if Ada's users are generally more careful with documentation,
> then that has a lot to do with their target applications: if an
> Android app crashes, who cares? but if a Boeing falls out of the sky,
> that's a problem.

I agree in general. However, in my experience traditionally aerospace 
projects have _not_ emphasized documentation in the source code, rather 
the opposite. Process standards require documentation separately from 
the source code, to the extent that testers/validators are more or less 
forbidden from looking at source code (and also from testing/validating 
code they have implemented themselves). It is not considered acceptable 
to require quality assurance staff to read source code; they must be 
given "documents", not code (which is also why tools that generate 
"documents", such as model-based design tools and Doxygen, are often used).

My impression is that Ada users are in general focused on "quality", 
correctness and thoroughness and are therefore attracted to and by a 
language that had its origins in such concerns, as exemplified by the 
style of the RM. This is not always driven by the criticality of the 
application.

> As far as I can tell, this has nothing at all to do with having two
> files versus having one file, and that's my point.

It seems likely to me -- partly based on introspection -- that the 
separation of spec files and implementation files helps the programmer 
separate, and keep in mind, the different roles and needs of the future 
_readers_ of the documentation: the documentation in the spec is for the 
clients/users of the package, while the documentation in the 
implementation is for the implementors/maintainers of the package.

Ideally, when writing the spec and its documentation the programmer 
should not even think of the implementation, but only of how the package 
can or should be used (particular aspects of the implementation, such as 
memory-management concerns, can sometimes imply usage rules, but that 
should be avoided if possible).

> Right. My quarrel, which is really more of an irritation, is with
> those whose arguments suggest they think it's impossible to generate
> specification / documentation from an implementation file, and that
> seems to keep coming up, so I just wanted to put a quick word in
> about it.

Whether it is possible or impossible depends on the exact meaning one 
assigns to "specification" and "implementation".

 From a simple coding-oriented point of view, the specification of a 
subprogram is just its parameter profile -- the declaration of the 
parameter types and return type. Clearly that can be generated from the 
implementation, at least in Ada where the parameter and return type 
declarations are repeated in the subprogram body.

However, from a higher-level design point of view, the specification of 
a subprogram would include preconditions, postconditions, precision 
requirements, execution-time requirements, and any other requirements on 
the subprogram's behaviour. Clearly those cannot be generated from an 
implementation, if "implementation" is understood as the body of the 
subprogram. The most that can be done is to check that the 
implementation satisfies the requirements stated in the specification. I 
think Dmitry takes this view, and I too.

However, if "implementation" is understood as a file of source text, 
which can include comments, requirements, pre/post-conditions, and so 
on, including markers to separate the "private" from the "public", then 
the "implementation" can in fact contain the "specification" and so the 
specification file can simply be extracted by filtering the 
implementation file (as has already been said in other messages in this 
thread).

Perhaps I should add that it is often possible to generate, from a 
subprogram body, some "weakest possible requirements" on the subprogram, 
which could be taken as a "specification". For example, the CodePeer 
tool from AdaCore can generate the weakest-possible precondition, on 
parameter values, that guarantees that the subprogram's execution fails 
no run-time constraint check. But such weakest-possible preconditions 
for "no failure" are usually almost irrelevant to the designed purpose 
and operation of the subprogram within the overall program, which is the 
focus of manually written specifications.

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

Re: Why .ads as well as .adb?

[Simon Wright]

John Perry <john.perry@usm.edu> writes:

> When I want to know how Ada.Text_IO works, I don't look up the
> specification file. I don't even know where to find Ada.Text_IO on my
> system. I just went to look for it, and gave up pretty quickly. I
> could probably find it if I tried hard enough, but it's far more
> convenient to visit [1], which has a hyperlink to Ada.Text_IO, as well
> as lots of other things.
>
> I imagine that [1] was generated by some software tool.

But not from an implementation. It's a reference manual, after all, a
specification, and it goes into much more detail than your example ...

> Similar tools exist for other languages. Take a look at [2] to see
> what a nice job they can do -- a LOT nicer than [1]. If I click on
> BINARY_SEARCH_TREE, not only do I get the specification for
> BINARY_SEARCH_TREE a la [1]

... well, I don't know Eiffel, so I can't really tell, but the first
thing I see is

   description: 
      "Binary search trees; left child item is less than current item,
      right child item is greater"

and I ask myself, does this mean that there can't be equal elements in
the tree?

> [1] http://www.ada-auth.org/standards/12rm/html/RM-TOC.html

This is the most up-to-date:
http://www.ada-auth.org/standards/rm12_w_tc1/html/RM-TOC.html

> [2] https://www.eiffel.org/files/doc/static/19.05/libraries/base/index.html

Re: Why .ads as well as .adb?

[John Perry]

On Sunday, June 9, 2019 at 4:37:49 PM UTC-5, Simon Wright wrote:
> > I imagine that [1] was generated by some software tool.
> 
> But not from an implementation. It's a reference manual, after all, a
> specification, and it goes into much more detail than your example ...

This gets back to one of my earlier questions, which I don't think was answered. (Apologies if it was; I've tried to follow everything.) You point out that it's a specification, but that's not a spec file, right?

If I understand correctly, I salute the culture that produces such a specification. The question, however, relates to the separation of spec file from implementation file. Was that generated from a spec file; i.e., an .ads?

> ... well, I don't know Eiffel, so I can't really tell, but the first
> thing I see is
> 
>    description: 
>       "Binary search trees; left child item is less than current item,
>       right child item is greater"
> 
> and I ask myself, does this mean that there can't be equal elements in
> the tree?

I think this is beside the point? That's not a function of spec files versus implementation files, is it?

> > [1] http://www.ada-auth.org/standards/12rm/html/RM-TOC.html
> 
> This is the most up-to-date:
> http://www.ada-auth.org/standards/rm12_w_tc1/html/RM-TOC.html

Thank you!

Re: Why .ads as well as .adb?

[Simon Wright]

John Perry <john.perry@usm.edu> writes:

> On Sunday, June 9, 2019 at 4:37:49 PM UTC-5, Simon Wright wrote:

 >> ... well, I don't know Eiffel, so I can't really tell, but the first
>> thing I see is
>> 
>>    description: 
>>       "Binary search trees; left child item is less than current item,
>>       right child item is greater"
>> 
>> and I ask myself, does this mean that there can't be equal elements
>> in the tree?
>
> I think this is beside the point? That's not a function of spec files
> versus implementation files, is it?

It'd be something that a specification should do, and a spec file would
be better off for stating it. Otherwise, what do I do? write a test
program to see whether it's OK or not? spend a lot of resource assuming
one way, only to find after delivery that it's actually the other?

Re: Why .ads as well as .adb?

[Niklas Holsti]

[ Apologies for duplication: I "sent" this post too early by mistake. ]

On 19-06-09 23:35 , John Perry wrote:

>  ...
>
> (2) I've read some very good arguments made in favor of separate
> specification files, but I don't understand why the conversation
> keeps coming around to "the specification file provides convenient
> documentation," or even, "if I want to see the specification from the
> implementation, I have to run a tool every time I want to see it, and
> that can be inconvenient." Those aren't just weak arguments; they're
> plainly false.

I disagree on the first part: specification files do provide convenient 
documentation. Of course, "convenient" may be subjective, but I feel 
sure that a file containing only the specification is more convenient 
than a file that interleaves specification and implementation, which is 
what this thread is about.

> When I want to know how Ada.Text_IO works, I don't look up the
> specification file.

I do, about half the time (the rest of the time I look it up in the RM).

> I don't even know where to find Ada.Text_IO on my
> system.

Your IDE (GPS) knows. And its not hard to find, either, once you figure 
out its file-name (with gnatkr).

> ... it's far more
> convenient to visit [1], which has a hyperlink to Ada.Text_IO, as
> well as lots of other things.

Sure the RM is often convenient, but it shows only the standard 
packages. Most of the packages in a non-trivial application will be 
application-specific.

> I imagine that [1] was generated by some software tool.

AIUI it was generated, but not from an Ada spec (.ads) file.

> Similar tools
> exist for other languages. Take a look at [2] to see what a nice job
> they can do -- a LOT nicer than [1].

Matter of opinion.

> If I click on
> BINARY_SEARCH_TREE, not only do I get the specification for
> BINARY_SEARCH_TREE a la [1], but I also get links to related
> specifications, such as COMPARABLE, TREE_ITERATION_CURSOR, and so
> forth. This is much, _much_ more helpful than the specification file
> by itself.

A good IDE will give you the same links from the specification file.

> Some have suggested that the markup required to do this can make the
> source file unreadable.

The markup makes the file less readable, IMO, but "unreadable" would be 
too strong a claim. No markup is really required for getting nice views 
of the descriptions and cross-links between declarations -- it is enough 
to follow some simple conventions for systematically locating 
descriptions (comments) close to the declarations they describe.

> Doxygen and javadoc markup aren't especially painful to read,
> either, and they do much the same thing.

I find them a little painful, though, and it seems that formatting 
conventions can produce much the same results without markup.

> Moreover, there's no need to invoke such a tool every time you want
> to see the specification, and thus no inconvenience at all.

While a program is being built, the specs of that program's specific 
packages change often, unlike the spec of standard packages like Text_IO.

> You
> generate the specification / documentation once and it ends up in a
> file that you can distribute just as easily as an .ads.

<RANT ON>
Oh yes, the Doxygen-generated "documentation". Typically it is as 
useless as the "User Manuals" for GUIs that just show screen-shots of 
various dialogs and explain things like "to frobnicate the lesneric, 
press the <Frobnicate the Lesneric> button -- without any coherent 
description of "frobnication" or "lesnerics".

Taking your reference [2] as an example, most high-level "descriptions" 
in it are one-liners, as usual in such "documentation". The reference is 
a little better than usual as it actually gives two or three (short) 
lines of description for many operations (although shown in a tiny, 
low-contrast font -- OK, I can magnify...)

I could point to some examples of the "frobicate/lesneric" problem in 
that example, that is, of concepts that are used in the descriptions but 
nowhere described themselves, but enough said.
</RANT OFF>

> The only time
> one has to invoke Doxygen, javadoc, etc. is if the exported objects
> change.

Which is often, when the program is being built. But of course this can 
be automated -- it is IMO _not_ the main problem with Doxygen-type 
documentation, and this is anyway not relevant to the subject of this 
thread: why Ada separates specifications from implementations.

> [1] http://www.ada-auth.org/standards/12rm/html/RM-TOC.html
> [2] https://www.eiffel.org/files/doc/static/19.05/libraries/base/index.html

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

Re: Why .ads as well as .adb?

[Dennis Lee Bieber]

On Sun, 9 Jun 2019 13:35:03 -0700 (PDT), John Perry <john.perry@usm.edu>
declaimed the following:

>When I want to know how Ada.Text_IO works, I don't look up the specification file. I don't even know where to find Ada.Text_IO on my system. I just went to look for it, and gave up pretty quickly. I could probably find it if I tried hard enough, but it's far more convenient to visit [1], which has a hyperlink to Ada.Text_IO, as well as lots of other things.
>
	If using GNAT, the standard libraries have "krunched" names...

C:\GNAT\2019\lib\gcc\x86_64-pc-mingw32\8.3.1\adainclude\a-textio.ads

(That's an easy one once you find the "adainclude" directory; others get
quite quite cryptic ... a-tgdico.ads for example.


-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
	wlfraed@ix.netcom.com    http://wlfraed.microdiversity.freeddns.org/

Re: Why .ads as well as .adb?

[Randy Brukardt]

"Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
news:47d02bdc-6b50-43aa-bc5d-bb5b6225f5bd@googlegroups.com...
>> Of course, you are essentially saying that separate
>> compilation is unnecessary and all of the source for a program should be 
>> in
>> one giant file
>
> Of course you are proving now that you did not understand the question 
> posted earlier in this thread.

No, you are proving that you refuse to comprehend my actual point: that 
source file organization is irrelevant (except maybe to compilers). You've 
never once said a word about the important point: reducing coupling. At this 
point, it appears that you are mainly trolling, and I don't have time to 
mess with such nonsense.

> 1. There *are* languages that don't use separate spec files. Java and
>Python are well known examples, representing both compiled and scripted 
>approaches.

Existence proves nothing about readability, suitability, or anything else. 
As I said at the outset, most languages did not try to design their syntax 
or language for readability as Ada did. (Java, for instance, pretty much 
decided to copy C's syntax, meaning of course that most of the faults were 
copied too. Little or no consideration was given to human factors because 
they simply "kicked the can" elsewhere.) Similarly, popularity doesn't tell 
us much about the quality of engineering (the relationship might even be 
weakly inverse).

                                   Randy.

Re: Why .ads as well as .adb?

[Optikos]

On Friday, June 7, 2019 at 11:57:59 PM UTC-5, Randy Brukardt wrote:
> "Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
> news:47d02bdc-6b50-43aa-bc5d-bb5b6225f5bd@googlegroups.com...
> >> Of course, you are essentially saying that separate
> >> compilation is unnecessary and all of the source for a program should be 
> >> in
> >> one giant file
> >
> > Of course you are proving now that you did not understand the question 
> > posted earlier in this thread.
> 
> No, you are proving that you refuse to comprehend my actual point: that 
> source file organization is irrelevant (except maybe to compilers). You've 
> never once said a word about the important point: reducing coupling.

How could Green team & Jean Ichbiah or Ada9X or some future Ada 2025-or-thereabouts go further than current Ada in reducing coupling?  One potential way that emerged long after Green team & HOLWG's efforts in the 1970s conceivably might be if HOLWG-operating-in-a-different-decade had mandated AOP aspects (as separation of concerns to the programmer) and requirements for weavers (as how the separation of concerns as axes are to intersect in a well-formed system).

And the leadership of the C++ community never has embraced AOP aspect weaving.  AOP is one of the few paradigms that C++ has not attempted (obtusely) to mimic.

Other than AOP, are there other potential ways beyond Ada's current capabilities that reducing coupling might be achieved?

> At this 
> point, it appears that you are mainly trolling,

I concur with that.

Re: Why .ads as well as .adb?

[Paul Rubin]

Optikos <optikos@verizon.net> writes:
> And the leadership of the C++ community never has embraced AOP aspect
> weaving.  AOP is one of the few paradigms that C++ has not attempted
> (obtusely) to mimic.

I think I've heard of some horrendous hacks to do this with C++ templates.
But I don't understand what AOP actually is, really.

Does Ada have anything like it?

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> No, you are proving that you refuse to comprehend my actual point: that 
> source file organization is irrelevant (except maybe to compilers).

Then why people are defending separate spec files so hard?

> You've 
> never once said a word about the important point: reducing coupling.

On the contrary. I have pointed that spec and implementations are coupled so much that people either generate fragments from one another or just copy-paste snippets around. And there are languages that decided to stop pretending that these are separate files and assigned separate roles to a single file instead. Now the coupling is gone, there is less clutter and the design patterns for large-scale code design are still available for those who really need them.

> At this 
> point, it appears that you are mainly trolling,

Or maybe you are just running out of arguments. Which is fine. I can accept the Ada history (just like I accept the C++'s one) without fighting it, but experiences with other languages allow me to ask questions from some wider perspective. And thus, perhaps, better understand the Ada rationale (or the lack of it (which is fine)).
What I don't accept is the religious attitude that Ada is the only language that got the software engineering right and (consequently) that everything else is broken. And I'm happy that this discussion was widened by introducing notions from more languages (Eiffel, etc.). This makes it even more interesting. Or me even more trolling - whatever you choose to see.

> > 1. There *are* languages that don't use separate spec files. Java and
> >Python are well known examples, representing both compiled and scripted 
> >approaches.
> 
> Existence proves nothing about readability, suitability, or anything else.

Another potential Ada beginner will resign after seeing this statement.

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[G.B.]

On 10.06.19 10:17, Maciej Sobczak wrote:
>> No, you are proving that you refuse to comprehend my actual point: that
>> source file organization is irrelevant (except maybe to compilers).
> 
> Then why people are defending separate spec files so hard?
> 
>> You've
>> never once said a word about the important point: reducing coupling.
> 
> On the contrary. I have pointed that spec and implementations are coupled so much that people either generate fragments from one another or just copy-paste snippets around. And there are languages that decided to stop pretending that these are separate files and assigned separate roles to a single file instead. Now the coupling is gone, there is less clutter and the design patterns for large-scale code design are still available for those who really need them.

"Need" is perhaps worth a little consideration.
Writing a spec requires expensive thought and work. And payment...

When a spec can be extracted from a source text of an implementation,
properly annotating for export seems like pretty much the same work to me.

One more point in favor of Ada's specific separations:

When writing contracts in terms of Pre, Post, ... aspects,
then these, too, have public parts in the spec and private parts
in the body. If Eiffel were to have this separation mapped to its
visibility specifications, the consequences will, I guess, simply
be too far-reaching. IIRC.

Re: Why .ads as well as .adb?

[Randy Brukardt]

"Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
news:bab5af5d-a3d7-412d-b3c9-1e573e2dd467@googlegroups.com...
> No, you are proving that you refuse to comprehend my actual point: that
> source file organization is irrelevant (except maybe to compilers).

Then why people are defending separate spec files so hard?

>> You've
>> never once said a word about the important point: reducing coupling.

>On the contrary. I have pointed that spec and implementations are coupled 
>so much

Of course they're coupled, they're views of the same thing (just like 
private types and full types are views of the same thing).

I was referrring to coupling *between* units. The specification of a unit 
typically depends only on a small number of other units (sometimes even 
none), while the implementation typically depends on many more 
(language-defined packages, implementation helpers, etc.). That's the 
coupling I'm worrying about, as it matters in a number of ways.

>> At this point, it appears that you are mainly trolling,

>Or maybe you are just running out of arguments.

Which would appear to be the same. :-) Since you belittle or ignore any 
serious argument, there's really no possibility of continuing. (It's OK to 
disagree, it's not OK to ignore all or [as in the case above], twist 
someone's discussion point into something unrecognizable.


>What I don't accept is the religious attitude that Ada is the only language
> that got the software engineering right and (consequently) that everything
>else is broken.

The truth hurts. So far as I can tell, no other language has really tried to 
"get software engineering right". It's possible, of course, but everyone 
either is trying to graft engineering onto some preexisting base without it 
(C++, Java) or is building something that's more about fast construction 
than engineering (Python).

...
>> Existence proves nothing about readability, suitability, or anything 
>> else.
>
>Another potential Ada beginner will resign after seeing this statement.

Good for them; they're not suitable for Ada if the truth bothers them that 
much.

                             Randy.

Re: Why .ads as well as .adb?

[Optikos]

On Monday, June 10, 2019 at 5:07:41 PM UTC-5, Randy Brukardt wrote:
> "Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
> news:bab5af5d-a3d7-412d-b3c9-1e573e2dd467@googlegroups.com...
> > No, you are proving that you refuse to comprehend my actual point: that
> > source file organization is irrelevant (except maybe to compilers).
> 
> Then why people are defending separate spec files so hard?
> 
> >> You've
> >> never once said a word about the important point: reducing coupling.
> 
> >On the contrary. I have pointed that spec and implementations are coupled 
> >so much
> 
> Of course they're coupled, they're views of the same thing (just like 
> private types and full types are views of the same thing).
> 
> I was referrring to coupling *between* units. The specification of a unit 
> typically depends only on a small number of other units (sometimes even 
> none), while the implementation typically depends on many more 
> (language-defined packages, implementation helpers, etc.). That's the 
> coupling I'm worrying about, as it matters in a number of ways.
> 
> >> At this point, it appears that you are mainly trolling,
> 
> >Or maybe you are just running out of arguments.
> 
> Which would appear to be the same. :-) Since you belittle or ignore any 
> serious argument, there's really no possibility of continuing. (It's OK to 
> disagree, it's not OK to ignore all or [as in the case above], twist 
> someone's discussion point into something unrecognizable.
> 
> 
> >What I don't accept is the religious attitude that Ada is the only language
> > that got the software engineering right and (consequently) that everything
> >else is broken.
> 
> The truth hurts. So far as I can tell, no other language has really tried to 
> "get software engineering right".

There was only one other programming language that tried to “get software engineering right” and that achieved significant industrial usage and an open-source GCC compiler and that was ISO standardized:  CHILL.  While DoD & NATO were busy with their HOLWG effort for the military, ITU-T (in the United Nations) launched a somewhat competing effort for telecom in the EU (and AT&T steadfastly rejected both for the most part except for some monitoring of the 2 other efforts, so that AT&T pushed forward with C).

As can be seen in the following example CHILL source code, if Ada was envisioned as a Pascal/Wirth-esque-family language, CHILL was envisioned as a PL/1esque-family language.  As such, Ada is beautiful & refined by comparison, whereas CHILL is rather abrupt & uncouth, as if it is most at home on an IBM mainframe with its fellow brethren CICS and JCL and of course PL/I.  CHILL and Ada share many of the same goals and as such have some analogous language features that are absent in most other programming languages.  Except for some maintenance of CHILL-based telecom equipment from Alcatel and Siemens, CHILL has become a dead language.
http://psc.informatik.uni-jena.de/languages/chill/chill.htm

> It's possible, of course, but everyone 
> either is trying to graft engineering onto some preexisting base without it 
> (C++, Java) or is building something that's more about fast construction 
> than engineering (Python).

I concur.  And the grafting on is not very aggressive at all.  It is as if the other languages that dip a toe into software-engineering principles are merely paying lip service to the topic.

Re: Why .ads as well as .adb?

[Brad Moore]

So far, the discussion has largely attempted to compare the approaches using very abstract analogies, without specific examples (eg books vs software programs).

I think it its probably a good idea to compare some real examples.

Consider a java class from an example of the n-body problem from the Computer Benchmarks Game website;

See https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-java-5.html

For the comparison, examine the NBodySystem class, which is the bulk of the example, which appears to be a well written java program.

Imagine someone handed you this class and you asked you to write a program that uses it. It takes a bit of reading to pull out the important parts, just to figure out how to use the class. Someone shouldn't have to wade through pages of implementation to figure out how to use the class. This simulation only has data for four planets. Imagine if it were modelling considerably more objects (asteroids, etc) in the solar system. There could be a lot of data to wade through, not to mention code. This is still a pretty simple program, classes in the real world often can be a lot more complex with larger implementations. 

If I were to directly translate that class into Ada, though, I'd likely end up with something like the following package specification.

--  Simulates orbits of the Jovian planets using a simple symplectic-integrator
--
package N_Body_System is

   procedure Reset_Simulation;
   
   procedure Advance (dt : Duration);
   
   function Energy return Long_Float;

end N_Body_System;


Although in Ada I'd want to also define a suitable type for the return object of the Energy function that would describe the units of result. I cannot easily tell by looking at the java example what the units are, and didn't bother digging in to find out. Of course, comments would also be helpful.

Because the N_Body_System is a singleton class in Java, there's no need to create an object for it in Ada, all the implementation details can be placed in the body of the package.

Rather than a constructor as in Java, I provided a Reset_Simulation call, in case someone wanted to rerun the simulation more than once (perhaps to measure a performance average)

To me, this provides a much simpler view for the client programmer. One can likely write a program to run the simulation without even looking at the implementation. If someone wants to understand the implementation, they can look at that if they really want to. I feel that having the language encourage you to intermix the specification and implementation together is really unappealing, from a system engineering point of view, in my opinion.

Brad

Re: Why .ads as well as .adb?

[John Perry]

On Tuesday, June 11, 2019 at 10:39:21 AM UTC-5, Brad Moore wrote:
> Consider a java class from an example of the n-body problem from the Computer Benchmarks Game website;
> 
> See https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-java-5.html
> 
> For the comparison, examine the NBodySystem class, which is the bulk of the example, which appears to be a well written java program.
> 
> Imagine someone handed you this class and you asked you to write a program that uses it. It takes a bit of reading to pull out the important parts, just to figure out how to use the class.

Why would someone hand you the source code? It's more likely they would hand you the output from javadoc, and you'd work with that.

john perry

Re: Why .ads as well as .adb?

[Shark8]

On Tuesday, June 11, 2019 at 10:14:33 AM UTC-6, John Perry wrote:
> On Tuesday, June 11, 2019 at 10:39:21 AM UTC-5, Brad Moore wrote:
> > Consider a java class from an example of the n-body problem from the Computer Benchmarks Game website;
> > 
> > See https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-java-5.html
> > 
> > For the comparison, examine the NBodySystem class, which is the bulk of the example, which appears to be a well written java program.
> > 
> > Imagine someone handed you this class and you asked you to write a program that uses it. It takes a bit of reading to pull out the important parts, just to figure out how to use the class.
> 
> Why would someone hand you the source code? It's more likely they would hand you the output from javadoc, and you'd work with that.

(a) Have you ever been employed in a small / medium software shop? In my experience its almost *always* that you "get handed the source code".
(b) You're assuming there is documentation, and that it is some level of quality that makes it usable/readable.
(c) Javadoc is *NOT* inherently usable/readable — Aside from things like "Parameter X is an integer" (Yes, I can see that!) There tends to be a bit of laziness WRT such suto-generated systems — see the comment upthread about "screenshots of the UI" and "'to frobnicate the lesneric, press the <Frobnicate the Lesneric> button' -- without any coherent description of 'frobnication' or 'lesnerics'."

Re: Why .ads as well as .adb?

[John Perry]

@Shark8, @joakim

[Shark8 wrote:]

> > Why would someone hand you the source code? It's more likely they would hand you the output from javadoc, and you'd work with that.
> 
> (a) Have you ever been employed in a small / medium software shop? In my experience its almost *always* that you "get handed the source code".

[Similarly, Joakim wrote:]

> John, if that's your experience from industry then I am very happy for you. I've worked for 12 years as software engineer since graduation from University and my experience is that one simply gets handed the code with very little explanation and/or comments/documentation.

In reply to Shark8, I worked at one such shop 25 years ago. They did embedded C programming. I was first handed a pretty thorough manual on SCSI devices. When I was done with that, I was handed a stack of magazines with articles on garbage collection, the topic they wanted me to work on. That's my experience of industry.

My experience of academia is actually worse than industry. When writing code for research purposes, I've had to decipher features few to no comments, and when I ask how something is supposed to work, I would sometimes get a wrong answer. In one particular case, the code had been written 30 years prior, perhaps even in a different language before porting over to C. On that one I eventually gave up and took a different route altogether (academia has its benefits).

So I definitely understand your argument here. On the other hand, what's the challenge in typing this?

   javadoc nbody.java

Unless you're handed the source code *on* *paper*, which I find a little hard to believe, that produces a specification of public and protected classes, methods, fields, etc. How is that different from the spec that Brad described?

> (b) You're assuming there is documentation, and that it is some level of quality that makes it usable/readable.

Brad's Ada example doesn't have much in the way of documentation, either. I doubt it has much more than javadoc would produce. For instance, it doesn't tell me whether I need to supply a command-line argument, as I do in the Java program (which crashes if I don't, and no, it isn't documented there, either).

Rosetta Code has lots of examples of not-particularly-highly-documented Ada code; see, for instance, ABC Problem.

> (c) Javadoc is *NOT* inherently usable/readable...

We'll have to agree to disagree here. I've developed quite a few applications using javadocs, and that includes eating from my own kitchen. I'm open to the idea that most programmers could write better documentation (I even stated as much above), and definitely that I should write better documentation, but the arguments advanced in this particular thread seem to be stating that Ada's separation of spec from implementation (the original question!) would *force* or *guarantee* that I write better comments, or get better documentation, and I just don't see that.

~~~

I apologize for dragging this on. I like Ada, and in most ways I prefer it to every other language I've looked at. I wish I'd met it much earlier. A lot of its seeming annoyances fix bugs that I've actually experienced, before they cause the program to crash. (I can think of 3 examples off the top of my head where using Ada would have saved me & C++ did not.) It is my intent to use it in the future.

Many answers to my question have been really helpful & illuminating; I just don't find this particular line compelling at all. I'm sorry. I think I've explain the difficulty I have with it, so I'll try not to repeat it again.

Re: Why .ads as well as .adb?

[Brad Moore]

On Tuesday, June 11, 2019 at 9:29:10 PM UTC+2, John Perry wrote:
> @Shark8, @joakim
> 
> [Shark8 wrote:]
> 
> > > Why would someone hand you the source code? It's more likely they would hand you the output from javadoc, and you'd work with that.

If I am, for example, reviewing someones code, I'd want to be looking directly at the code, not indirectly through some computer generated filter of that code. I would not trust that important details and errors are being omitted in the filtered output. It is the code that needs to be maintained after all. It should be in a form that is readable, and easy to understand. I should not have to run some external tool to be able to make sense of what the programmer has written. I've also seen plenty of cases where computer generated documentation can be a mess to read for complex systems, so I tend to avoid using them altogether.

> So I definitely understand your argument here. On the other hand, what's the challenge in typing this?
> 
>    javadoc nbody.java
> 
> Unless you're handed the source code *on* *paper*, which I find a little hard to believe, that produces a specification of public and protected classes, methods, fields, etc. How is that different from the spec that Brad described?

For code reviews, paper might well be the medium, or it could some online format such as html, or PDF file, etc.

> 
> > (b) You're assuming there is documentation, and that it is some level of quality that makes it usable/readable.
> 
> Brad's Ada example doesn't have much in the way of documentation, either. I doubt it has much more than javadoc would produce. For instance, it doesn't tell me whether I need to supply a command-line argument, as I do in the Java program (which crashes if I don't, and no, it isn't documented there, either).

In my post, I was talking specifically about the NBodySystem class, not the enclosing class that includes the main program test driver. That represents client code that one would write to exercise the NBodySystem class member functions. The reading of command line parameters is part of the main test driver program, not the NBodySystem class.

But doing this exercise highlights another benefit of having separate specs and bodies. When reviewing someones code, one needs to wear multiple hats. Designing a good interface can be as important as the implementation. When I review code where both the spec and implementation are intermixed, as in the Java case, I am trying to wear multiple hats at the same time, and would not as likely have noticed that the type of the return value of the Energy function (double) does not provide any indication on the units. When looking at specs and implementation separately, I can wear a different hat when reviewing each, and looking at the Ada spec, I am more likely to notice that as a client programmer, I cannot use the specs, without understanding the units, so I would raise a comment on the review asking for the type of the return value for Energy be a type name that describes the units. 

Brad

Re: Why .ads as well as .adb?

[John Perry]

@Brad, @Dave

Those answers are very helpful & Brad's answer especially helps me see that issue more clearly. Thank you!

My apologies if I've overlooked thanking anyone!

john perry

On Friday, June 14, 2019 at 1:12:51 AM UTC-5, Brad Moore wrote:
> On Tuesday, June 11, 2019 at 9:29:10 PM UTC+2, John Perry wrote:
> > @Shark8, @joakim
> > 
> > [Shark8 wrote:]
> > 
> > > > Why would someone hand you the source code? It's more likely they would hand you the output from javadoc, and you'd work with that.
> 
> If I am, for example, reviewing someones code, I'd want to be looking directly at the code, not indirectly through some computer generated filter of that code. I would not trust that important details and errors are being omitted in the filtered output. It is the code that needs to be maintained after all. It should be in a form that is readable, and easy to understand. I should not have to run some external tool to be able to make sense of what the programmer has written. I've also seen plenty of cases where computer generated documentation can be a mess to read for complex systems, so I tend to avoid using them altogether.
> 
> > So I definitely understand your argument here. On the other hand, what's the challenge in typing this?
> > 
> >    javadoc nbody.java
> > 
> > Unless you're handed the source code *on* *paper*, which I find a little hard to believe, that produces a specification of public and protected classes, methods, fields, etc. How is that different from the spec that Brad described?
> 
> For code reviews, paper might well be the medium, or it could some online format such as html, or PDF file, etc.
> 
> > 
> > > (b) You're assuming there is documentation, and that it is some level of quality that makes it usable/readable.
> > 
> > Brad's Ada example doesn't have much in the way of documentation, either. I doubt it has much more than javadoc would produce. For instance, it doesn't tell me whether I need to supply a command-line argument, as I do in the Java program (which crashes if I don't, and no, it isn't documented there, either).
> 
> In my post, I was talking specifically about the NBodySystem class, not the enclosing class that includes the main program test driver. That represents client code that one would write to exercise the NBodySystem class member functions. The reading of command line parameters is part of the main test driver program, not the NBodySystem class.
> 
> But doing this exercise highlights another benefit of having separate specs and bodies. When reviewing someones code, one needs to wear multiple hats. Designing a good interface can be as important as the implementation. When I review code where both the spec and implementation are intermixed, as in the Java case, I am trying to wear multiple hats at the same time, and would not as likely have noticed that the type of the return value of the Energy function (double) does not provide any indication on the units. When looking at specs and implementation separately, I can wear a different hat when reviewing each, and looking at the Ada spec, I am more likely to notice that as a client programmer, I cannot use the specs, without understanding the units, so I would raise a comment on the review asking for the type of the return value for Energy be a type name that describes the units. 
> 
> Brad

Re: Why .ads as well as .adb?

[djakoogler]

John,

There is one point in this discussion no has raised yet: There
may be several different implementations (bodies) for a given
specification.

In VHDL, a hardware design language which based itself on
Ada83 concepts, there is a specification for logic function.
The language allows for "architecture behavioral" and
"architecture structural" implementations against the
specification. The "behavioral" implementation defines the
defines the behavior of the function as an algorithm (much
as you write the function in Ada), while the "structural"
implementation gives a very precise gate-level or netlist
description of the function (how you actually do the function
with digital components). I believe there may be a third
such "architecture" available to describe an analog
(transistor) level description.

While Ada does not explicitly provide for parallel
implementations, you may find many GNAT based projects the
use the naming facilities of a GNAT Project File (.gpr) to
select different bodies to match certain configurations.
For instance, you may want to have one implementation which
is a stub and maybe has some tracing statements, and another
implementation which has the complete algorithm. Another
common variation is one implementation for Unix and another
for Windows. By using environment variables when launching
gprbuild, the user selects which bodies to use. To be
complete, you can use the same naming technique for specs
as well as bodies.

If you look at it in the right way, you can see where Java
and Ada interfaces are to do something similar except
interfaces allow the user to make a run-time selection not
a build-time selection. For my work with small machines,
I almost always need just one implementation at run-time
so build-time selection is the way I go.

Dave Koogler
Engineer

Re: Why .ads as well as .adb?

[joakimds]

> Why would someone hand you the source code? It's more likely they would hand you the output from javadoc, and you'd work with that.

John, if that's your experience from industry then I am very happy for you. I've worked for 12 years as software engineer since graduation from University and my experience is that one simply gets handed the code with very little explanation and/or comments/documentation. The situation is often due to stress, lack of time and requirements that has been changed during the life-time of the code etc.

When working with Java I often make use of "the Outline" in the IDE being used in the project. It gives an overview of the Java code for example list of functions and so on. Perhaps that would be a better example than the use of JavaDoc in a Java project to get a high level view of the Java code.

The arguments for and against having a separate spec. and body have been laid bare in this discussion thread. Thanks to everybody for contributing to it.

Best regards,
Joakim

Re: Why .ads as well as .adb?

[Jeffrey R. Carter]

On 6/11/19 12:07 AM, Randy Brukardt wrote:
> 
> So far as I can tell, no other language has really tried to
> "get software engineering right".

Precisely. It's important to remember that separation of spec and body have been 
part of Ada from the beginning, and Ada was designed to support the way S/W 
engineers think and work from the beginning. Like many Ada features, S/W 
engineers understand and like separation of spec and body, and coders don't. For 
me, much of this thread can be viewed simply as people saying "I'm a S/W 
engineer" or "I'm a coder".

-- 
Jeff Carter
"They name the boy Jonathan Ralph Starkwell,
after Virgil's mother."
Take the Money and Run
141

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-05 17:28 , Niklas Holsti wrote:

I wrote:

> Most of my specs contain mostly type declarations, with a smattering of
> subprogram declarations -- no, in fact most of my specs contain mostly
> comments to explain the types and to specify and explain what the
> subprograms (should) do.

An amusing but unfortunate side-effect of such extensive comments in the 
spec is that, for simpler subprograms, few or perhaps no comments are 
needed in the body -- which often makes static source-code analysers 
complain that the comment-to-code ratio is too small, because the 
analyser only counts the comments in the subprogram's body... :-(

This problem might be solved by merging the spec and body in the same 
file. Or, of course, by making the source-code analysers a bit smarter.

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

Re: Why .ads as well as .adb?

[Randy Brukardt]

Maciej Sobczak" <see.my.homepage@gmail.com> wrote in message 
news:f611bdb8-5a40-48bd-afe5-17de72bbe193@googlegroups.com...
>> On the other hand, I like it that I can get a first impression of an Ada
>> program by reading just the .ads files.

...
>Say, I need this idiom in 10% of packages. Why am I
>penalized in the remaining 90% and forced to write specs
>that are demonstrably not needed?

I think you have this percentage backwards. You need this idiom in a 
significant majority of packages, certainly in anything object-based. I 
would have given the percentages as more like 80% need it and 20% don't.

After all, anything that doesn't benefit from separate specs really 
shouldn't be in a package in the first place. It might be in a package since 
some other package got unmanageably large (Janus/Ada has a lot of these, 
especially because of the size limits when it originally was created), but 
my experience is that such things are impediments to understanding the 
program and in finding where things really are. So it is best to avoid them.

...
>> Apart from all the other reasons already given, keeping spec and body in
>> the same file can cause compilation-order problems.
>
>Only if you assume that the compiler reads the file only once and therefore
>must validate everything in a single pass.

There's two parts to this. The first part is true of almost every compiler 
(GNAT is a weird exception). That's in large part because compiler 
performance is mostly bound by I/O time (memory management overhead taking 
much of the rest); outside of optimization, compilation simply doesn't do 
enough to show up in a CPU monitor (and this has been true for decades, at 
least since the early 1990s). The less I/O a compiler does, the faster it's 
build times are going to be. (Which probably doesn't matter for one file, 
but it certainly matters for systems with hundreds of units.)

The other part is true, but seems irrelevant. The issue being the increased 
coupling of putting all of the source in one file (which I do do from 
time-to-time). Before one can compile a source file, all of it dependencies 
have to exist and be compilable as well. Which means that when the body and 
spec are together, you have to have much more of the program compilable 
before any part of it (and the files that depend on it as well) can be 
compiled. But compiling is the best way to stamp out mistakes, and it has 
been proven that the earlier that you can catch a bug, the cheaper it is to 
fix. Delaying compilation just makes it more likely that you've forgotten 
part of your intent before the problem shows up.

>Which is not the case anyway, not even in Ada (nor in C++). That's why this
>concept looks a bit archaic today.

The concept of decreasing coupling seems just as relevant today as it was 
when it was designed into Ada 83. After all, a well-designed unit will only 
reference a handful of things in the specification and many things in the 
body. Mixing them increases the coupling for the compiler and for the 
reader.

                                        Randy.


                             Randy. 

Re: Why .ads as well as .adb?

[Keith Thompson]

Maciej Sobczak <see.my.homepage@gmail.com> writes:
> "Randy Brukardt" <randy@rrsoftware.com> writes:
[...]
>> And C-family code with } on separate lines is a rarity
>
> Not in my world. Actually, this is the only style I happen to work
> with. This style is promoted by all industrial coding standards (both
> C and C++ language standards examples, MISRA-C, JSF, HICPP, AUTOSAR,
> ...), so I don't get the argument about "rarity".
>
> Actually, I don't even know where to find something different.

The two most common layouts for C code are:

1. Opening "{" at the end of the line, closing "}" by itself, aligned
   with the beginning of the construct:
    if (condition) {
        statement;
        statement;
    }

2. Opening "{" and closing "}" on lines by themselves:
    if (condition)
    {
        statement;
        statement;
    }

(I have my own preference, but this isn't the place to go into it.)

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[Maciej Sobczak]

> > This style is promoted by all industrial coding standards (both
> > C and C++ language standards examples, MISRA-C, JSF, HICPP, AUTOSAR,
> > ...), so I don't get the argument about "rarity".
> >
> > Actually, I don't even know where to find something different.
> 
> The two most common layouts for C code are:
[...]

Of course. But as pointed above, the vertically-aligned braces are promoted by all industrial coding standards and are used in code examples of the language standards themselves. And I see them in classic books. And I see them in major open source code bases.
Hence my comment about the argument that "most" C code is smushed together. I just don't see that. (But I know Java coders who, when forced to put their dignity aside, would actually write C code this way.)

In either case (in both styles) the argument that "Ada's comb" is superior is just not convincing. Which might explain why every new programming language either adopts C-style braces or resigns from distinct bracketing altogether. The subsequent argument that the whole world is idiots would not be convincing, either - this apparently is an inherent property of our visual system that delimiters need be visible enough to be noticed, but should not dominate over the actual (delimited) content.

Note: sentences are delimited by dots. Just like the sentence you are reading right now. And parts are delimited by commas, just like, you know, the parts of this very sentence.
And it worked for ages. And we are used to it so much that we would refuse anything different.

Why?

Because our very brains are wired exactly to expect that.

Do you think it would be better to have delimiters and separators that areQWERTY you knowQWERTY so bigQWERTY that they take significant part of the spaceQWERTY with huge terminatorsQWERTY tooQWERTY so that we can see them betterASDFGHJ?

I don't think soASDFGHJ.

;-)

-- 
Maciej Sobczak * http://www.inspirel.com

Re: Why .ads as well as .adb?

[John Perry]

First, this has gotten way off topic. Thanks to everyone who replied, and who followed up to my other questions. I appreciate it.

Anyway:

On Thursday, June 6, 2019 at 2:29:30 AM UTC-5, Maciej Sobczak wrote:
> In either case (in both styles) the argument that "Ada's comb" is superior is just not convincing. Which might explain why every new programming language either adopts C-style braces or resigns from distinct bracketing altogether. The subsequent argument that the whole world is idiots would not be convincing, either - this apparently is an inherent property of our visual system that delimiters need be visible enough to be noticed, but should not dominate over the actual (delimited) content.

I think this is due to the prevalence of brace-delimiter languages as a first language, and the fact that those who learn something one way think everything else should work the same way. I've had conversations with students to that very effect.

I learned Pascal at university, and even though I use C++ a lot, I have never grown to like braces as delimiters, precisely because they can be a bit hard to spot at times. I don't think it an accident that there's an annual "Obfuscated C Programming Contest" [1] and there was an "Obfuscated Perl Contest" [2] but no "Obfuscated Ada Programming Contest" (to my knowledge, anyway).

When I first heard of Python's use of colon + indentation, I thought it was ridiculous, in part because I thought that anything that didn't use begin/end was ridiculous. (I was younger & stupider than now.) However, once I actually read some Python code, and started writing it, I realized that this is actually a really good idea. (Sorry if this makes me look horrible, but it's my opinion.)

Funny enough, my students often struggle with getting Python's indentation correct. In any case, I don't think it an accident that languages that focus on safety and careful programming use variants of "begin" and "end".

> Note: sentences are delimited by dots. Just like the sentence you are reading right now. And parts are delimited by commas, just like, you know, the parts of this very sentence.
> And it worked for ages. And we are used to it so much that we would refuse anything different.
> 
> Why?
> 
> Because our very brains are wired exactly to expect that.
> 
> Do you think it would be better to have delimiters and separators that areQWERTY you knowQWERTY so bigQWERTY that they take significant part of the spaceQWERTY with huge terminatorsQWERTY tooQWERTY so that we can see them betterASDFGHJ?

IMHO this argument doesn't work the way you think. What you're actually talking about here compares to semicolons, not to braces or begin/end. Both C and Ada use semicolons.

Braces or begin/end are used for blocks of related code. In print, we separate blocks of related text by paragraphs, which have a lot of space and/or indentation. Chapters of a text start with much larger text, often titles, and often conclude with graphics.

In mathematics, the beginning and end of a proof are both delimited by special symbols (e.g., "Proof." and "QED" or a box)

So I think you're comparing apples and oranges here.

[1] https://www.ioccc.org
[2] https://en.wikipedia.org/wiki/Obfuscated_Perl_Contest

Re: Why .ads as well as .adb?

[Brad Moore]

On Thursday, June 6, 2019 at 1:29:30 AM UTC-6, Maciej Sobczak wrote:
> > > This style is promoted by all industrial coding standards (both
> > > C and C++ language standards examples, MISRA-C, JSF, HICPP, AUTOSAR,
> > > ...), so I don't get the argument about "rarity".
> > >
> > > Actually, I don't even know where to find something different.
> > 
> > The two most common layouts for C code are:
> [...]
> 
> Of course. But as pointed above, the vertically-aligned braces are promoted by all industrial coding standards and are used in code examples of the language standards themselves. And I see them in classic books. And I see them in major open source code bases.
> Hence my comment about the argument that "most" C code is smushed together. I just don't see that. (But I know Java coders who, when forced to put their dignity aside, would actually write C code this way.)
> 
> In either case (in both styles) the argument that "Ada's comb" is superior is just not convincing. Which might explain why every new programming language either adopts C-style braces or resigns from distinct bracketing altogether. The subsequent argument that the whole world is idiots would not be convincing, either - this apparently is an inherent property of our visual system that delimiters need be visible enough to be noticed, but should not dominate over the actual (delimited) content.
> 
> Note: sentences are delimited by dots. Just like the sentence you are reading right now. And parts are delimited by commas, just like, you know, the parts of this very sentence.
> And it worked for ages. And we are used to it so much that we would refuse anything different.
> 
> Why?
> 
> Because our very brains are wired exactly to expect that.
> 
> Do you think it would be better to have delimiters and separators that areQWERTY you knowQWERTY so bigQWERTY that they take significant part of the spaceQWERTY with huge terminatorsQWERTY tooQWERTY so that we can see them betterASDFGHJ?
> 
> I don't think soASDFGHJ.
> 
> ;-)

I think you are somewhat comparing apples and oranges here. A sentence in English is more comparable to a statement in Ada. The delimiter for statements in most programming languages including Ada is a semi-colon, which is a single character. I'm guessing semi-colon was chosen over period, as it is less ambiguous for floating point declarations, and otherwise is more noticeable with similar semantics in English.

More comparable to a declarative region in English text is the section title as can be found in outline paragraph titles, and in chapter titles.

Often such declarations provide some sort of number to uniquely identify the section of text, and a descriptive name that describes the text to follow.

For English text, some simplications can be applied, since typically all "declarative regions" are declaring the same variables of the same types, with different data for the object instances. A numerical section id, and a textual short description. In programming languages, these declarative regions are more complex typically, and more critical to understanding the text that follows. 

Typically such declarative regions are further distinguished with preceding blank space including a carriage return, possibly a new page, a unique (larger) font, and then followed by a carriage return, and more blank space.

Pick any book off your bookshelf, you'll likely see this same pattern.

If we truly believe that shortening the "syntax" of these declarative regions is a good idea, then we should eliminate the carriage returns, blank space, font changes, etc from the document sections and chapter headers of all the literature.

1.0 intoduction It was a dark and stormy night, ... 2.0 the early years Way back in the old days...
;-)

Having a longer sequence of text in the syntax for paragraph titles, even if only blank space, can be helpful. Some authors add to this with syntax including the word "Chapter" for example. It doesn't necessarily add a lot of clarity for the reader, but isn't considered annoying either.

I think a bigger issue is using the same syntax for multiple constructs. In languages like C, you typically need to use comments to label end braces for deeply nested code to assist readability. And comments can be misleading. In Ada, different constructs use different (but similar) syntax, such as "end loop", "end select" end {subprogram name}, with optional block labels, which aids the reader in understanding which declarative contruct is ending. And with optional labels also allows the compiler to confirm that what the reader sees matches what the compiler sees. 

Brad

Re: Why .ads as well as .adb?

[Keith Thompson]

Maciej Sobczak <see.my.homepage@gmail.com> writes:
>> > This style is promoted by all industrial coding standards (both
>> > C and C++ language standards examples, MISRA-C, JSF, HICPP, AUTOSAR,
>> > ...), so I don't get the argument about "rarity".
>> >
>> > Actually, I don't even know where to find something different.
>> 
>> The two most common layouts for C code are:
> [...]
>
> Of course. But as pointed above, the vertically-aligned braces are
> promoted by all industrial coding standards and are used in code
> examples of the language standards themselves. And I see them in
> classic books. And I see them in major open source code bases.  Hence
> my comment about the argument that "most" C code is smushed
> together. I just don't see that. (But I know Java coders who, when
> forced to put their dignity aside, would actually write C code this
> way.)

This is off-topic, but the style used in the documents that define
the C and C++ languages is to put the opening "{" for a function
definition on a line by itself, but the opening "{" for any control
structure (if/while/for) is at the end of the line.  (There are
historical reasons for the difference, which I won't go into.)

    int func(int arg)
    {
        if (arg > 0) {
            do_this;
        }
        else {
            do_that;
        }
    }

It's also common to put the opening "{" for the function at the end of
the line.

-- 
Keith Thompson (The_Other_Keith) kst-u@mib.org  <http://www.ghoti.net/~kst>
Will write code for food.
void Void(void) { Void(); } /* The recursive call of the void */

Re: Why .ads as well as .adb?

[Dennis Lee Bieber]

On Wed, 05 Jun 2019 20:34:49 -0700, Keith Thompson <kst-u@mib.org>
declaimed the following:

>The two most common layouts for C code are:
>
>1. Opening "{" at the end of the line, closing "}" by itself, aligned
>   with the beginning of the construct:
>    if (condition) {
>        statement;
>        statement;
>    }
>
>2. Opening "{" and closing "}" on lines by themselves:
>    if (condition)
>    {
>        statement;
>        statement;
>    }
>
>(I have my own preference, but this isn't the place to go into it.)

	I've encountered at least one editor that has three style options.

	if (condition)
		{
			statement block;
		}

being the third. (I abhor it as it uses two indentation levels per block.
My preference is your #2).

{Actually, VS2017 has something like 6 styles which can be used if it can't
find a file of clang formatting rules -- was going to check CCS9, but it
seems to insist on downloading any updates and then checking all files
before it will open... A significant time waster}


-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
	wlfraed@ix.netcom.com    http://wlfraed.microdiversity.freeddns.org/

Re: Why .ads as well as .adb?

[joakimds]

Den söndag 2 juni 2019 kl. 02:48:18 UTC+2 skrev John Perry:
> Hello
> 
> I understand that Ada, like Modula-2 and Modula-3, and arguably like C++, requires a definition file (.ads) as well as an implementation file (.adb). With Oberon, Wirth moved away from definition files, using a symbol to indicate which module identifiers should be exported. (Someone else may have done this before him; it's just that I'm most familiar with this history.) Most languages I'm familiar with these days do something similar, either via public/private or some other mechanism.
> 
> As far as I can tell, though, Ada has stuck with the two separate files, rather than, say, generating an .ads from an .adb with export markup.
> 
> Is there a reason Ada hasn't moved to this simpler structure?
> 
> john perry

Expanding on what Dmitry wrote it is not possible to generate specifications from the implementation. Consider for example a simple function that takes an integer as input and multiplies with 10 and then returns the result:

function Multiply_By_10 (I : Integer) return Integer is
begin
   return 10*I;
end Multiply_By_10;

One might think that the specification/declaration of this function is merely

function Multiply_By_10 (I : Integer) return Integer;

but with contract-based programming it is possible to specify that the contract for the integer argument must be a number between 1 and 10 and the result must be a number between 10 and 100.

function Multiply_By_10 (I : Integer) return Integer with
   Pre  => I >= 1 and I <= 10,
   Post => Multiply_By_10'Result >= 10 and Multiply_By_10'Result <= 100;

The pre- and post-conditions may be important for static code analysis tools to prove/verify that an application is correctly implemented. Note that the information needed to specify the pre- and post-conditions are missing in the implementation. One could perhaps auto-generate pre- and post-conditions from the body but it will probably not correspond to what the developer wishes to set up as a contract for the subprogram. From my experience, the specification of contracts can be many, many lines of code. To be able to cleanly separate the contracts from the implementations is very useful and convenient.

Re: Why .ads as well as .adb?

[G.B.]

On 02.06.19 02:48, John Perry wrote:
> Hello
> 
> I understand that Ada, like Modula-2 and Modula-3, and arguably like C++, requires a definition file (.ads) as well as an implementation file (.adb). With Oberon, Wirth moved away from definition files, using a symbol to indicate which module identifiers should be exported. (Someone else may have done this before him; it's just that I'm most familiar with this history.) Most languages I'm familiar with these days do something similar, either via public/private or some other mechanism.

Not entirely true, IMO, insofar as other languages offer to separate
the interface from all implementations, using abstract classes,
or protocols, as in Swift, say. On top of this, Microsoft has
introduced partial classes.

By not extracting the interface like in Oberon style (which
also features abstract classes IIRC), but instead by providing
the interface as a separate entity, effects are generated that
can be seen as beneficial in some business situations:

- there is more flexibility in trying out different implementations,
   simply through software configuration;

- teams can work separated from each other as needed, without the
   project having to distribute all of the implementation to everyone.

 From a configuration point of view, Ada's *separate* units are
an additional feature that may be useful in similar situations.
For example, separate units can provide debugging/tracing/whatever
editions of a piece of software so that neither the specification
nor the body stub of the unit needs to be changed whenever the
configuration is changed. This effect is transitive, at all call sites.

Re: Why .ads as well as .adb?

[John Perry]

Thanks to everyone for the replies. Personally, I find three of them especially compelling:

   "As a teacher, I keep fighting with students who jump to writing bodies too early."

[I know exactly what this is like.]

   "teams can work separated from each other as needed, without the project having to distribute all of the implementation to everyone"

[Having separate specification files against which one can *compile* would be useful, not just convenient, though I think it's arguable that one can do this in Oberon, too, via .smb files and documentation.]

   "convenience"

[not a direct quote, but several people point to this, and until I read their explanations I thought the convenience ran in the other direction]

Originally I had intended no further reply, since I was just curious for information / opinions; I don't mean this as a criticism of Ada. That said, when reflecting on some of the subsequent discussion, I began to wonder if people misunderstood what I asked, or if I have misunderstood what they're saying. So I hope people don't mind if I follow up.

I'll preface the reply by quoting myself a moment:

> With Oberon, Wirth moved away from definition files, using a symbol to indicate which module identifiers should be exported.

I don't have the citation handy, but I recall reading that Wirth's stated motivation for doing this was his realization that definition modules can be generated from an implementation module, something that both Oberon and several other languages have done since then. All a language needs for this are keywords and/or markup in comments. Every Oberon compiler I've used can generate at least a machine-readable symbol file (.smb), and many that I've used provide tools that generate a human-readable HTML file. One can compile against a symbol file without having the object code. And of course Java, Eiffel, etc. offer tools to generate specifications and/or documentation from a source file.

So I was surprised that some people made absolute negations of the possibility along these lines:

    "You can't generate specification from implementation."

I especially wonder this since one of them had just referred to gnatchop, whose online documentation provides an example that does precisely that [1]. So, when I read statements like the ones above, I wonder (a) if people understand that I don't mean Ada-as-is, but a hypothetically modified Ada (I am not proposing such a modification Ada; again, it's just curiosity); and (b) if I misunderstand what people mean by "specification".

If (a) is true, then I think there is no need to continue the discussion along those lines; if (b) is true, I'd appreciate someone clarifying what they mean by "specification", since one can generate [2] from the OBNC compiler, and that seems to me to be a specification that can be, for instance, published, shared among teams, etc., even if the actual implementation is not complete.

If I'm still not being clear, please don't hesitate to point out where I'm vague, or misusing terms. Sorry if that's the case.

[1] http://sandbox.mc.edu/~bennet/ada/gnat_ug/gnat_ug_8.html#SEC78

[2] https://miasap.se/obnc/obncdoc/basic/In.def.html

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-03 16:37 , John Perry wrote:
> Thanks to everyone for the replies. Personally, I find three of them
> especially compelling:
>
> "As a teacher, I keep fighting with students who jump to writing
> bodies too early."
>
> [I know exactly what this is like.]

The separation (and early creation) of .ads files from .adb files was 
the main reason cited for the success of the first Ada project at my 
alma mater (a Prolog system -- this was during the "5th generation" 
fad). That project had markedly fewer integration and interfacing 
problems than earlier projects implemented in (an extended) Pascal.

> "teams can work separated from each other as needed, without the
> project having to distribute all of the implementation to everyone"
>
> [Having separate specification files against which one can *compile*
> would be useful, not just convenient, though I think it's arguable
> that one can do this in Oberon, too, via .smb files and
> documentation.]

If an Ada project needs to use an Ada library that is not open-source 
and was developed by someone else, the library provider can deliver the 
.ads source files to define the library API, but deliver only the object 
code for the .adb files, thus keeping the library implementation secret. 
Can Oberon .smb files do that?

In Ada this can be done even if the library is actually implemented in 
some other language such as C.

> "convenience"
>
> [not a direct quote, but several people point to this, and until I
> read their explanations I thought the convenience ran in the other
> direction]

When I write client code for a package, I find it much more convenient 
to study the package's interface from its .ads file, because the .ads 
file is usually shorter than the .adb file and contains only information 
useful to the client (up to the "private" part). However, I admit that a 
smart IDE could display a filtered view of a "combined .ads/.adb" file, 
showing me only the interface and not the implementation.

> So I was surprised that some people made absolute negations of the
> possibility along these lines:
>
> "You can't generate specification from implementation."

That is true, IMO, for current Ada, but I'm sure that Ada could be 
extended with pragmas or keywords to allow a combined .ads/.adb file 
from which a "pure .ads" could be extracted. But I don't see any 
advantage in that, given the other advantages of separate .ads and .adb.

> I especially wonder this since one of them had just referred to
> gnatchop, whose online documentation provides an example that does
> precisely that [1].

No, gnatchop reads a source file that is a simple concatenation of any 
number of .ads and .adb files, and just finds the boundaries of the 
concatenated files and spits out the separated (de-concatenated) files. 
It is a bit like "unzip" but uses Ada syntax to separate out the 
individual files from the "archive" (the concatenated file).

Ada compilers other than GNAT accepted such concatenated input source 
files as "compilations". Gnatchop was implemented to help apply GNAT to 
such source files.

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

Re: Why .ads as well as .adb?

[John Perry]

On Monday, June 3, 2019 at 9:50:03 AM UTC-5, Niklas Holsti wrote:
> > "teams can work separated from each other as needed, without the
> > project having to distribute all of the implementation to everyone"
> >
> > [Having separate specification files against which one can *compile*
> > would be useful, not just convenient, though I think it's arguable
> > that one can do this in Oberon, too, via .smb files and
> > documentation.]
> 
> If an Ada project needs to use an Ada library that is not open-source 
> and was developed by someone else, the library provider can deliver the 
> .ads source files to define the library API, but deliver only the object 
> code for the .adb files, thus keeping the library implementation secret. 
> Can Oberon .smb files do that?

Yes; that's the entire point of an .smb file. The Oberon compilers I'm familiar with generate both symbol (.smb) and object files (.o or .class, depending on the target). I've tested that they will check a module against .smb, without having an object file.

In Native Oberon, unexpected record fields are kept secret [1]. Wirth states in "Modula-2 and Oberon" [2] that symbol files have an advantage over source files, in that the compiler can record a version number with the file, and automatically update it.

> In Ada this can be done even if the library is actually implemented in 
> some other language such as C.

An Oberon compiler that targets native code allows one to create modules that define interfaces to C files [3]. Another, which targets the JVM, allows one to create modules that define interfaces to Java class files. [4]

> When I write client code for a package, I find it much more convenient 
> to study the package's interface from its .ads file, because the .ads 
> file is usually shorter than the .adb file and contains only information 
> useful to the client (up to the "private" part). However, I admit that a 
> smart IDE could display a filtered view of a "combined .ads/.adb" file, 
> showing me only the interface and not the implementation.

Right, this latter is what I'm referring to in general.

> That is true, IMO, for current Ada, but I'm sure that Ada could be 
> extended with pragmas or keywords to allow a combined .ads/.adb file 
> from which a "pure .ads" could be extracted. But I don't see any 
> advantage in that, given the other advantages of separate .ads and .adb.

That's fine; as I said, I'm curious. I've noticed that Ada's designers aren't reticent to adopt what they think are good ideas from other languages (e.g., Eiffel's contracts) so that made me wonder why the .ads/.adb distinction was retained, at least in gnat. (I'm not actually aware if that's required by the language itself.)

> No, gnatchop reads a source file that is a simple concatenation of any 
> number of .ads and .adb files, and just finds the boundaries of the 
> concatenated files and spits out the separated (de-concatenated) files. 
> It is a bit like "unzip" but uses Ada syntax to separate out the 
> individual files from the "archive" (the concatenated file).
> 
> Ada compilers other than GNAT accepted such concatenated input source 
> files as "compilations". Gnatchop was implemented to help apply GNAT to 
> such source files.

I completely misunderstood that. Thank you.

BTW, in case it hasn't been clear: there are plenty of ways I think Ada is far superior to Oberon. This is just one aspect of Oberon that originally I didn't like (when I was a Modula-2 programmer), and came to appreciate greatly only later.

john perry

[1] inf.ethz.ch/personal/wirth/Articles/Modula-Oberon-June.doc

[2] www.ethoberon.ethz.ch/native/compiler/obj081200/ObjectFile.html

[3] miasap.se/obnc/man/obnc.txt; see "Interfacing to C".

[4] github.com/lboasso/oberonc

Re: Why .ads as well as .adb?

[Niklas Holsti]

On 19-06-03 22:23 , John Perry wrote:
> On Monday, June 3, 2019 at 9:50:03 AM UTC-5, Niklas Holsti wrote:
>>> "teams can work separated from each other as needed, without the
>>>  project having to distribute all of the implementation to
>>> everyone"
>>>
>>> [Having separate specification files against which one can
>>> *compile* would be useful, not just convenient, though I think
>>> it's arguable that one can do this in Oberon, too, via .smb
>>> files and documentation.]
>>
>> If an Ada project needs to use an Ada library that is not
>> open-source and was developed by someone else, the library
>> provider can deliver the .ads source files to define the library
>> API, but deliver only the object code for the .adb files, thus
>> keeping the library implementation secret. Can Oberon .smb files do
>> that?
>
> Yes; that's the entire point of an .smb file. The Oberon compilers
> I'm familiar with generate both symbol (.smb) and object files (.o
> or .class, depending on the target). I've tested that they will check
> a module against .smb, without having an object file.

Well and good! However (and as you said) the Oberon library must also be
documented in some human-readable form (I assume the .smb files are not
human-readable). In contrast the .ads files are human-readable (or at
least programmer-readable). But perhaps Doxygen-type tools erase that
difference between Ada and Oberon.

(Personally I avoid Doxygen -- the source-code annotations feel ugly,
decreasing both writability and readability. I much prefer tools that
make code browsable and inter-linked without such annotations, for
example gnathtml or an IDE like GPS, although these tools currently have 
some draw-backs in the source formatting they require.)

> Wirth states in "Modula-2 and Oberon" [2] that symbol files have an
> advantage over source files, in that the compiler can record a
> version number with the file, and automatically update it.

For GNAT, the compiler-generated .ali (Ada Library Information) files
have timestamps etc. that serve that function, to check that the object
files correspond to the .ads files.

All Ada compilers are expected to check consistency of sources (as last 
compiled) and objects at bind/link-time, but I'm not sure if all 
compilers have the ability to do that when importing object code 
compiled by other parties into their program library.

> ... so that made me
> wonder why the .ads/.adb distinction was retained, at least in gnat.
> (I'm not actually aware if that's required by the language itself.)

The language requires that a package must have both a declaration and a 
body. These conform to different non-terminal symbols in the grammar and 
correspond to GNAT's .ads and .adb files. The language further requires 
the user to compile (or provide for compilation) the declaration before 
compiling the body, but the language does not require that the 
declaration text and the body text be in separate text files.

In fact there is a non-terminal grammar symbol "compilation" that is a 
sequence of "compilation units", such as package declarations and 
bodies, and the standard says that an entire "compilation" can be 
submitted to the compiler. That's essentially why gnatchop was created.

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

Re: Why .ads as well as .adb?

[Lucretia]

On Monday, 3 June 2019 14:37:46 UTC+1, John Perry  wrote:

> So I was surprised that some people made absolute negations of the possibility along these lines:
> 
>     "You can't generate specification from implementation."

I knew Wirth had done this already, but he missed the point.
 
> I especially wonder this since one of them had just referred to gnatchop, whose online documentation provides an example that does precisely that [1]. So, when I read statements like the ones above, I wonder (a) if people understand that I don't mean Ada-as-is, but a hypothetically modified Ada (I am not proposing such a modification Ada; again, it's just curiosity); and (b) if I misunderstand what people mean by "specification".

In Ada, I've written code which is organised like this:

src/blah.ads
src/blah.adb
src/linux/blah-separate.adb
src/windows/blah-separate.adb
src/meh.ads
src/linux/meh.adb
src/windows/meh.adb
etc.

blah.ads is the interface to that package, it is what every OS sees, one interface, that's it. blah.adb is the body where it's portable. separate.adb contains a "separate" which is a subprogram which is separated from the blah.adb because it's platform specific. In the gpr file, I enable the OS specific directories. The meh package is similar except it has a whole body which is platform specific and therefore separated into the OS specific directory.

You can, if you want, create constants for the OS as well somewhere, i.e.

Inside src/oses.ads:

package OSes
   type OS is (Linux, Windows, etc.);
end OSes;

Inside src/linux/platforms.ads:

-- Similar for Windows.

with OSes;

package Platforms
   OS : constant OSes.OS := Linux;
end Platforms;

Then inside actual code:

with Platforms;

...

case Platforms.OS is
   when Platforms.Linux =>
      -- Linux code.
   when others =>
      -- Should be stripped from the final binary.
end case;

This method gives you compile time code stripping due to a static type system and the constant OS, platform specific code in a directory and using stubs in platform specific directories. It's very powerful and a shitload less messy than C and C++ methods of makefiles and preprocessor.

Luke.

Re: Why .ads as well as .adb?

[John Perry]

On Monday, June 3, 2019 at 1:51:33 PM UTC-5, Lucretia wrote:
> In Ada, I've written code which is organised like this:
> 
> src/blah.ads
> src/blah.adb
> src/linux/blah-separate.adb
> src/windows/blah-separate.adb
> src/meh.ads
> src/linux/meh.adb
> src/windows/meh.adb
> etc.

Someone else wrote something about this, though I can't find it now. I was filing that under "convenience" in my previous reply. However, this answer seems more thorough, so thank you for the elaboration.

john perry

Re: Why .ads as well as .adb?

[Jeffrey R. Carter]

On 6/2/19 2:48 AM, John Perry wrote:
> 
> As far as I can tell, though, Ada has stuck with the two separate files, rather than, say, generating an .ads from an .adb with export markup.
> 
> Is there a reason Ada hasn't moved to this simpler structure?

First, let me point out that your specification is GNAT-specific, but your body 
is compiler-independent. I'm going to presume that the generation of the spec 
from the body was faulty.

Others have given you the good reasons related to S/W engineering in the large 
(more than 1 person). They provide a formal and compiler-checked way to state 
what each person is working on, and allow the development of parts of the S/W 
that depend on other parts that have not been implemented yet.

I have not seen any responses that address the use of specs to represent and 
check high-level design decisions. This can be very helpful.

Nor have I seen any responses that deal with specs as a way to deal with the 
limitations of the human brain. When a system reaches a certain size, whether 
developed by a single person or a team, it becomes impossible to keep the entire 
system in one's head. Specs reduce the amount of information that must be retained.

I recall reading a quote by a famous S/W engineer: "I have only a small brain 
and must learn to live with it." I don't recall who, and I can't find it on 
line. Reducing the amount of information kept in the brain is what he meant by 
learning to live with it. Separate specs are a mechanism for that.

In another post, you wrote

> So I was surprised that some people made absolute negations of the possibility along these lines:
> 
>     "You can't generate specification from implementation."
> 
> I especially wonder this since one of them had just referred to gnatchop, whose online documentation provides an example that does precisely that [1].

Note that gnatchop does not generate specifications from bodies, and the example 
does not show that. It shows an input file containing 2 compilation units, a 
spec and a body. gnatchop produces a single file for each compilation unit in 
its input.

-- 
Jeff Carter
"I fart in your general direction."
Monty Python & the Holy Grail
05

Re: Why .ads as well as .adb?

[Lucretia]

On Monday, 3 June 2019 18:00:24 UTC+1, Jeffrey R. Carter  wrote:

> I have not seen any responses that address the use of specs to represent and 
> check high-level design decisions. This can be very helpful.
> 
> Nor have I seen any responses that deal with specs as a way to deal with the 
> limitations of the human brain. When a system reaches a certain size, whether 
> developed by a single person or a team, it becomes impossible to keep the entire 
> system in one's head. Specs reduce the amount of information that must be retained.

I think I can, https://github.com/Lucretia/sdlada

Luke.

Re: Why .ads as well as .adb?

[John Perry]

On Monday, June 3, 2019 at 12:00:24 PM UTC-5, Jeffrey R. Carter wrote:
> On 6/2/19 2:48 AM, John Perry wrote:
> > 
> > As far as I can tell, though, Ada has stuck with the two separate files, rather than, say, generating an .ads from an .adb with export markup.
> > 
> > Is there a reason Ada hasn't moved to this simpler structure?
> 
> First, let me point out that your specification is GNAT-specific, but your body 
> is compiler-independent. I'm going to presume that the generation of the spec 
> from the body was faulty.

I'm not sure what you mean, but you & Nicholas have made me aware that the premises of my question are not entirely well-founded, in that I'm basing them on my experience with gnat, since I don't really have access to another Ada compiler (to my knowledge). I do recall reading that gnat has a particular addition to the requirements that every file contain only one compilation unit, so spec & impl need to be in separate files.

> Note that gnatchop does not generate specifications from bodies, and the example 
> does not show that. It shows an input file containing 2 compilation units, a 
> spec and a body. gnatchop produces a single file for each compilation unit in 
> its input.

That was indeed a poorly thought out reply of mine; thank you.

john perry

Re: Why .ads as well as .adb?

[Jeffrey R. Carter]

On 6/3/19 9:29 PM, John Perry wrote:
> On Monday, June 3, 2019 at 12:00:24 PM UTC-5, Jeffrey R. Carter wrote:
>>
>> First, let me point out that your specification is GNAT-specific, but your body
>> is compiler-independent. I'm going to presume that the generation of the spec
>> from the body was faulty.
> 
> I'm not sure what you mean, but you & Nicholas have made me aware that the premises of my question are not entirely well-founded, in that I'm basing them on my experience with gnat, since I don't really have access to another Ada compiler (to my knowledge). I do recall reading that gnat has a particular addition to the requirements that every file contain only one compilation unit, so spec & impl need to be in separate files.

I was jokingly pointing out that your Subject line (spec) refers to GNAT's 
default naming scheme, while the text of your post (body) was about general Ada 
features.

-- 
Jeff Carter
"I fart in your general direction."
Monty Python & the Holy Grail
05