Re: Why .ads as well as .adb?

[Niklas Holsti <niklas.holsti@tidorum.invalid>]

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
       .      @       .