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=-0.9 required=5.0 tests=BAYES_00,FORGED_GMAIL_RCVD, FREEMAIL_FROM autolearn=no autolearn_force=no version=3.4.4 X-Received: by 2002:ad4:43c9:: with SMTP id o9mr6686678qvs.113.1560492770613; Thu, 13 Jun 2019 23:12:50 -0700 (PDT) X-Received: by 2002:a9d:3ee2:: with SMTP id b89mr34356086otc.342.1560492770364; Thu, 13 Jun 2019 23:12:50 -0700 (PDT) Path: eternal-september.org!reader01.eternal-september.org!feeder.eternal-september.org!weretis.net!feeder6.news.weretis.net!feeder.usenetexpress.com!feeder-in1.iad1.usenetexpress.com!border1.nntp.dca1.giganews.com!nntp.giganews.com!j96no605616qte.0!news-out.google.com!33ni56qtt.0!nntp.google.com!j96no605614qte.0!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail Newsgroups: comp.lang.ada Date: Thu, 13 Jun 2019 23:12:50 -0700 (PDT) In-Reply-To: Complaints-To: groups-abuse@google.com Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=212.180.180.250; posting-account=lzqe5AoAAADHhp_gregSufVhvwu22fBS NNTP-Posting-Host: 212.180.180.250 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> User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: <1da5ba01-055a-491a-b30a-cdd733445c85@googlegroups.com> Subject: Re: Why .ads as well as .adb? From: Brad Moore Injection-Date: Fri, 14 Jun 2019 06:12:50 +0000 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Xref: reader01.eternal-september.org comp.lang.ada:56634 Date: 2019-06-13T23:12:50-07:00 List-Id: 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 wou= ld 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 direc= tly at the code, not indirectly through some computer generated filter of t= hat code. I would not trust that important details and errors are being omi= tted in the filtered output. It is the code that needs to be maintained aft= er 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 g= enerated 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? >=20 > javadoc nbody.java >=20 > 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 clas= ses, methods, fields, etc. How is that different from the spec that Brad de= scribed? For code reviews, paper might well be the medium, or it could some online f= ormat such as html, or PDF file, etc. >=20 > > (b) You're assuming there is documentation, and that it is some level o= f quality that makes it usable/readable. >=20 > 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 does= n't tell me whether I need to supply a command-line argument, as I do in th= e 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 represent= s 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 wou= ld not as likely have noticed that the type of the return value of the Ener= gy function (double) does not provide any indication on the units. When loo= king at specs and implementation separately, I can wear a different hat whe= n reviewing each, and looking at the Ada spec, I am more likely to notice t= hat as a client programmer, I cannot use the specs, without understanding t= he units, so I would raise a comment on the review asking for the type of t= he return value for Energy be a type name that describes the units.=20 Brad