Re: Why .ads as well as .adb?

[Brad Moore <bmoore.ada@gmail.com>]

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