From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=unavailable autolearn_force=no version=3.4.4 Path: eternal-september.org!reader01.eternal-september.org!feeder.eternal-september.org!news.swapon.de!fu-berlin.de!uni-berlin.de!individual.net!not-for-mail From: Niklas Holsti Newsgroups: comp.lang.ada Subject: Re: Why .ads as well as .adb? Date: Mon, 10 Jun 2019 12:22:40 +0300 Organization: Tidorum Ltd Message-ID: References: <28facad3-c55f-4ef2-8ef8-004925b7d1f1@googlegroups.com> <87woi0xtwm.fsf@nightsong.com> <4a0438de-1f1d-4469-aae4-908854d378ea@googlegroups.com> <47d02bdc-6b50-43aa-bc5d-bb5b6225f5bd@googlegroups.com> <455333f0-ede4-4833-900a-240a499395ac@googlegroups.com> <875zphvufc.fsf@nightsong.com> <87y32bvbeo.fsf@nightsong.com> <561c766c-4f9c-432c-be9b-822dd9c3c8ba@googlegroups.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: individual.net ztV4DdYeO8pLmezqCKW7KwY/kQrMtJlu8b2PJaJICozMQ7f2Cu Cancel-Lock: sha1:PiPhETV8JwgZgp+UO1stmNibniE= User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 In-Reply-To: Xref: reader01.eternal-september.org comp.lang.ada:56597 Date: 2019-06-10T12:22:40+03:00 List-Id: 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 >> 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 . @ .