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,FREEMAIL_FROM autolearn=unavailable autolearn_force=no version=3.4.4 X-Received: by 2002:a24:7546:: with SMTP id y67-v6mr603990itc.26.1539876277917; Thu, 18 Oct 2018 08:24:37 -0700 (PDT) X-Received: by 2002:a9d:c42:: with SMTP id 60mr564459otr.7.1539876277808; Thu, 18 Oct 2018 08:24:37 -0700 (PDT) Path: eternal-september.org!reader01.eternal-september.org!reader02.eternal-september.org!feeder.eternal-september.org!news.gegeweb.eu!gegeweb.org!usenet-fr.net!proxad.net!feeder1-2.proxad.net!209.85.166.216.MISMATCH!x98-v6no17736ita.0!news-out.google.com!n199-v6ni36itn.0!nntp.google.com!z5-v6no17803ite.0!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail Newsgroups: comp.lang.ada Date: Thu, 18 Oct 2018 08:24:37 -0700 (PDT) In-Reply-To: Complaints-To: groups-abuse@google.com Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=50.66.161.135; posting-account=lzqe5AoAAADHhp_gregSufVhvwu22fBS NNTP-Posting-Host: 50.66.161.135 References: <7fcdcc97-67e4-473b-abc4-cd0ecd4501ad@googlegroups.com> <8f6c0bfa-f7ed-4bee-a766-c786269f13a1@googlegroups.com> User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: Subject: Re: Is the Documentation In a spec File Usually Enough For You ? From: Brad Moore Injection-Date: Thu, 18 Oct 2018 15:24:37 +0000 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Xref: reader02.eternal-september.org comp.lang.ada:54629 Date: 2018-10-18T08:24:37-07:00 List-Id: It should also be mentioned that with Ada 2012, the addition of contracts h= elps also aid to reader of a spec understand what a subprogram does, and ho= w it was intended to be used by the author.=20 A problem with documentation is that it can become stale if not maintained,= whereas the contracts are assertions in the code and thus tend to be more = accurate.=20 A designer of a package should consider, for example, what pre and post con= ditions should be applied to the subprograms of that package. The addition = of contracts tends to simplify the documentation that is needed. As an example, in the standard package Ada.Locales, there is; type Country_Code is new String (1 .. 2) with Dynamic_Predicate =3D> (for all E of Country_Code =3D> E in 'A' .. 'Z'); function Country return Country_Code; If we didn't have the contract for Dynamic_Predicate on the Country_Code ty= pe,=20 we would need to document that the function Country returns a 2 character s= tring where all the characters of the string consist of capital letters fro= m A to Z inclusive. =20 With the contract, this doesn't need to be documented, and the contract is = more concise for the reader than having to read a full paragraph of text. F= urther, anywhere the Country_Code result is used in the user's program, it = is clear that the contract holds, since it is a property of the type. If the implementation changes in a way that breaks the contracts, then this= tends to get caught, and either the implementation is adjusted to meet the= contracts, or the contracts are adjusted to meet the implementation. Gener= ally one tries to avoid making changes to contracts, particularly if there = are existing users of those contracts. Brad