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 X-Received: by 2002:a37:a413:: with SMTP id n19mr25321865qke.98.1560549070242; Fri, 14 Jun 2019 14:51:10 -0700 (PDT) X-Received: by 2002:aca:ea05:: with SMTP id i5mr3108752oih.51.1560549069855; Fri, 14 Jun 2019 14:51:09 -0700 (PDT) Path: eternal-september.org!reader01.eternal-september.org!feeder.eternal-september.org!weretis.net!feeder6.news.weretis.net!4.us.feeder.erje.net!feeder.erje.net!feeder.usenetexpress.com!feeder-in1.iad1.usenetexpress.com!border1.nntp.dca1.giganews.com!nntp.giganews.com!j96no1365016qte.0!news-out.google.com!33ni150qtt.0!nntp.google.com!j96no1365005qte.0!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail Newsgroups: comp.lang.ada Date: Fri, 14 Jun 2019 14:51:09 -0700 (PDT) In-Reply-To: <1da5ba01-055a-491a-b30a-cdd733445c85@googlegroups.com> Complaints-To: groups-abuse@google.com Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=2601:3c3:401:f550:b818:4f8b:142f:828; posting-account=JSxOkAoAAADa00TJoz2WZ_46XrZCdXeS NNTP-Posting-Host: 2601:3c3:401:f550:b818:4f8b:142f:828 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> <4516d350-0076-4dc7-b482-87d5693d3977@googlegroups.com> <0c9a9692-5fa2-46ba-8649-d5bddcc88a3f@googlegroups.com> <1da5ba01-055a-491a-b30a-cdd733445c85@googlegroups.com> User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: <852db18b-f6a9-483d-9db9-31d94b5fb841@googlegroups.com> Subject: Re: Why .ads as well as .adb? From: John Perry Injection-Date: Fri, 14 Jun 2019 21:51:10 +0000 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Xref: reader01.eternal-september.org comp.lang.ada:56639 Date: 2019-06-14T14:51:09-07:00 List-Id: @Brad, @Dave Those answers are very helpful & Brad's answer especially helps me see that= issue more clearly. Thank you! My apologies if I've overlooked thanking anyone! john perry On Friday, June 14, 2019 at 1:12:51 AM UTC-5, Brad Moore wrote: > On Tuesday, June 11, 2019 at 9:29:10 PM UTC+2, John Perry wrote: > > @Shark8, @joakim > >=20 > > [Shark8 wrote:] > >=20 > > > > Why would someone hand you the source code? It's more likely they w= ould hand you the output from javadoc, and you'd work with that. >=20 > If I am, for example, reviewing someones code, I'd want to be looking dir= ectly at the code, not indirectly through some computer generated filter of= that code. I would not trust that important details and errors are being o= mitted in the filtered output. It is the code that needs to be maintained a= fter 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 wha= t 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 te= nd to avoid using them altogether. >=20 > > So I definitely understand your argument here. On the other hand, what'= s the challenge in typing this? > >=20 > > javadoc nbody.java > >=20 > > Unless you're handed the source code *on* *paper*, which I find a littl= e hard to believe, that produces a specification of public and protected cl= asses, methods, fields, etc. How is that different from the spec that Brad = described? >=20 > For code reviews, paper might well be the medium, or it could some online= format such as html, or PDF file, etc. >=20 > >=20 > > > (b) You're assuming there is documentation, and that it is some level= of quality that makes it usable/readable. > >=20 > > Brad's Ada example doesn't have much in the way of documentation, eithe= r. I doubt it has much more than javadoc would produce. For instance, it do= esn'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 the= re, either). >=20 > In my post, I was talking specifically about the NBodySystem class, not t= he enclosing class that includes the main program test driver. That represe= nts client code that one would write to exercise the NBodySystem class memb= er functions. The reading of command line parameters is part of the main te= st driver program, not the NBodySystem class. >=20 > But doing this exercise highlights another benefit of having separate spe= cs and bodies. When reviewing someones code, one needs to wear multiple hat= s. Designing a good interface can be as important as the implementation. Wh= en 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 w= ould not as likely have noticed that the type of the return value of the En= ergy function (double) does not provide any indication on the units. When l= ooking at specs and implementation separately, I can wear a different hat w= hen 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.=20 >=20 > Brad