Re: Why .ads as well as .adb?

[John Perry <john.perry@usm.edu>]

(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