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-Google-Thread: a07f3367d7,429176cb92b1b825 X-Google-Attributes: gida07f3367d7,public,usenet X-Google-NewGroupId: yes X-Google-Language: ENGLISH,CP1252 Path: g2news2.google.com!news1.google.com!postnews.google.com!g26g2000vbz.googlegroups.com!not-for-mail From: "pascal.obry@gmail.com" Newsgroups: comp.lang.ada Subject: Re: AWS Coding Styles (and about boring plain-linear text files in the end) Date: Mon, 17 Jan 2011 02:23:12 -0800 (PST) Organization: http://groups.google.com Message-ID: <24418fa4-8843-4fe6-8c2f-026ea6009b68@g26g2000vbz.googlegroups.com> References: NNTP-Posting-Host: 82.124.201.129 Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: quoted-printable X-Trace: posting.google.com 1295259793 1451 127.0.0.1 (17 Jan 2011 10:23:13 GMT) X-Complaints-To: groups-abuse@google.com NNTP-Posting-Date: Mon, 17 Jan 2011 10:23:13 +0000 (UTC) Complaints-To: groups-abuse@google.com Injection-Info: g26g2000vbz.googlegroups.com; posting-host=82.124.201.129; posting-account=PEdGtgoAAACjNhf4BGsFw-AboVux6xYy User-Agent: G2/1.0 X-HTTP-Via: 1.1 lancelot:3128 (squid/2.7.STABLE9) X-HTTP-UserAgent: Mozilla/5.0 (X11; U; Linux i686; fr; rv:1.9.1.16) Gecko/20110107 Iceweasel/3.5.16 (like Firefox/3.5.16),gzip(gfe) Xref: g2news2.google.com comp.lang.ada:17446 Date: 2011-01-17T02:23:12-08:00 List-Id: Yannick, > In =933.5 Comments=94 : > > =A0 =A0 > The only exception to this rule (i.e. one space is > =A0 =A0 > tolerated) is when the comment ends with -- > > =A0 =A0 Q: Why a comment could ends with =93--=94 ? What could this mean = ? File header (boxed style comment). > In =933.5 Comments=94 : > > =A0 =A0 > Comments describing a subprogram spec should specifically > =A0 =A0 > mention the formal argument names. General rule: write a > =A0 =A0 > comment that does not depend on the names of things. > > =A0 =A0 Q: I am afraid I did not understood this one, as it seems > =A0 =A0 =A0 =A0ambiguous to me. How to refer to formal argument names > =A0 =A0 =A0 =A0without refering to the names of things ? Or else, are > =A0 =A0 =A0 =A0does =93names of things=94 refer to in this context ? Instead of saying: procedure Call (Filename : String); -- The name of the file should be an absolute name Say: procedure Call (Filename : String); -- Filename must be an abosulute name > In =934 Declarations and Types=94 : > > =A0 =A0 > Declarations should be grouped in a logical order. > > =A0 =A0 Q: What about circular dependencies ? I use to think > =A0 =A0 =A0 =A0about the same rule for myself, but oftenly failed > =A0 =A0 =A0 =A0due to circular dependencies matters (i.e. when there > =A0 =A0 =A0 =A0is iterative evaluation as an example). I would say that "logical" here cover this case. There is now way around that anyway. > In =934 Declarations and Types=94 : > > =A0 =A0 > All local subprograms in a subprogram or package body > =A0 =A0 > should be declared before the first local subprogram > =A0 =A0 > body. > > =A0 =A0 Q: Why this requirement of a declaration for body's and > =A0 =A0 =A0 =A0procedure's local subprograms ? Is it to avoid the > =A0 =A0 =A0 =A0need to order subprogram bodies with respect to their > =A0 =A0 =A0 =A0dependencies to each others ? (if so, this would > =A0 =A0 =A0 =A0be contradictory with previous quote). First this force having a spec and the spec must be commented. Second it is better to group all specs together for maintenance and code review. You have all local subprograms in a single place. > In =936.2 If Statements=94 : > > =A0 =A0 > Complex conditions in if-statements are indented two > =A0 =A0 > characters > > =A0 =A0 Q: I've already seen about this convention in some other > =A0 =A0 =A0 =A0places, while I could never understand it. Not that I > =A0 =A0 =A0 =A0disagree, just want to know, because this may mean > =A0 =A0 =A0 =A0there is something relevant I've never though about. > =A0 =A0 =A0 =A0Is that to shorten line length ? Is that to just have > =A0 =A0 =A0 =A0a different indent than the one which come for =93when=94 > =A0 =A0 =A0 =A0parts of =93case=94 statements ? No strong opinion on this one. 2 spaces is shorter than 3 sure, but as for many convention it is just a convention. Note that this is what Emacs and GPS does, so helpful I would say. > Not questions now, personal talks: > > In =938 Packages and Visibility Rules=94 : > > =A0 =A0 > Do not with two times the same unit, always use the > =A0 =A0 > deepest child unit to with. For example do not write: > =A0 =A0 > =A0 =A0 =A0 =A0 =A0 =A0with Ada.Strings; > =A0 =A0 > =A0 =A0 =A0 =A0 =A0 =A0with Ada.Strings.Unbounded; > =A0 =A0 > but the equivalent form: > =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0with Ada.Strings.Unbounded; > > =A0 =A0 I always do the opposite. I feel it is clearer if I > =A0 =A0 refer to the parent unit. If I don't, I do not withed > =A0 =A0 the parent unit (i.e. I state something about usage in > =A0 =A0 the withed declarations). Fine, just another convention. > In =939 Packages and Visibility Rules=94 : > > =A0 =A0 > It is good to group the context clauses in 3 parts. > =A0 =A0 > The Ada standard clauses, the components from other > =A0 =A0 > projects and then the project's clauses. In each > =A0 =A0 > group it is required to sort the clauses by alphabetical > =A0 =A0 > order. > > =A0 =A0 Adding some grouping by roles is also nice when the context > =A0 =A0 clause may be long (by the way, the grouping presented in > =A0 =A0 this design guide-lines is compliant with a grouping by > =A0 =A0 roles). Ok. > Ah, a big one deal for me this one=85 (the one which follows) > > In =933.1 Character Set and Separators=94 : > > =A0 =A0 > A line should never be longer than 79 characters, > =A0 =A0 > not counting the line separator. > > =A0 =A0 I fully agree with this is some sense (just that I use 78 > =A0 =A0 characters instead of 79). But I agree only at the display > =A0 =A0 side, not at the source side. Let me explain One of the most important points are: 1. readability, it is hard to read too long line 2. maintainability, code review as it is almost impossible to read a diff for too long lines. > P.S. Thanks for the =93Short comments that fit on a single line are NOT = =A0 > ended with a period.=94 in =933.5 Comment=94 : I oftenly had the same que= stion =A0 > for myself, and could never make a final decision about it. If you decide= d =A0 > and make it a standard, well, let's go for this one and follow it. This is also GNAT standard. > P.P.S. No, no, I am not to work on AWS source, I was just reading it =A0 > driven by curiosity. :p :) Pascal.