Re: Why .ads as well as .adb?

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

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