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=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,429176cb92b1b825,start X-Google-NewGroupId: yes X-Google-Attributes: gida07f3367d7,domainid0,public,usenet X-Google-Language: ENGLISH,UTF8 Path: g2news2.google.com!news3.google.com!feeder.news-service.com!94.75.214.39.MISMATCH!aioe.org!not-for-mail From: =?utf-8?Q?Yannick_Duch=C3=AAne_=28Hibou57?= =?utf-8?Q?=29?= Newsgroups: comp.lang.ada Subject: AWS Coding Styles (and about boring plain-linear text files in the end) Date: Mon, 17 Jan 2011 06:07:58 +0100 Organization: Ada @ Home Message-ID: NNTP-Posting-Host: 8YsgJzdbsnaSVMKLcUWmzQ.user.speranza.aioe.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed; delsp=yes Content-Transfer-Encoding: Quoted-Printable X-Complaints-To: abuse@aioe.org X-Notice: Filtered by postfilter v. 0.8.2 User-Agent: Opera Mail/11.00 (Win32) Xref: g2news2.google.com comp.lang.ada:17441 Date: 2011-01-17T06:07:58+01:00 List-Id: Hi happy night workers, If ever Pascal or his peer for that project is around the place=E2=80=A6= I get AWS = source, not to compile nor use it, but just to have a look (I enjoy = reading others literatures, and especially surrounding design = documentations). There are things about I have questions. The file style-guide.html says In =E2=80=9C3.5 Comments=E2=80=9D : > The only exception to this rule (i.e. one space is > tolerated) is when the comment ends with -- Q: Why a comment could ends with =E2=80=9C--=E2=80=9D ? What could t= his mean ? In =E2=80=9C3.5 Comments=E2=80=9D : > Comments describing a subprogram spec should specifically > mention the formal argument names. General rule: write a > comment that does not depend on the names of things. Q: I am afraid I did not understood this one, as it seems ambiguous to me. How to refer to formal argument names without refering to the names of things ? Or else, are does =E2=80=9Cnames of things=E2=80=9D refer to in this context ?= In =E2=80=9C4 Declarations and Types=E2=80=9D : > Declarations should be grouped in a logical order. Q: What about circular dependencies ? I use to think about the same rule for myself, but oftenly failed due to circular dependencies matters (i.e. when there is iterative evaluation as an example). In =E2=80=9C4 Declarations and Types=E2=80=9D : > All local subprograms in a subprogram or package body > should be declared before the first local subprogram > body. Q: Why this requirement of a declaration for body's and procedure's local subprograms ? Is it to avoid the need to order subprogram bodies with respect to their dependencies to each others ? (if so, this would be contradictory with previous quote). In =E2=80=9C6.2 If Statements=E2=80=9D : > Complex conditions in if-statements are indented two > characters Q: I've already seen about this convention in some other places, while I could never understand it. Not that I disagree, just want to know, because this may mean there is something relevant I've never though about. Is that to shorten line length ? Is that to just have a different indent than the one which come for =E2=80=9Cwhen=E2=80= =9D parts of =E2=80=9Ccase=E2=80=9D statements ? Not questions now, personal talks: In =E2=80=9C8 Packages and Visibility Rules=E2=80=9D : > Do not with two times the same unit, always use the > deepest child unit to with. For example do not write: > with Ada.Strings; > with Ada.Strings.Unbounded; > but the equivalent form: with Ada.Strings.Unbounded; I always do the opposite. I feel it is clearer if I refer to the parent unit. If I don't, I do not withed the parent unit (i.e. I state something about usage in the withed declarations). In =E2=80=9C9 Packages and Visibility Rules=E2=80=9D : > It is good to group the context clauses in 3 parts. > The Ada standard clauses, the components from other > projects and then the project's clauses. In each > group it is required to sort the clauses by alphabetical > order. Adding some grouping by roles is also nice when the context clause may be long (by the way, the grouping presented in this design guide-lines is compliant with a grouping by roles). Ah, a big one deal for me this one=E2=80=A6 (the one which follows) In =E2=80=9C3.1 Character Set and Separators=E2=80=9D : > A line should never be longer than 79 characters, > not counting the line separator. I fully agree with this is some sense (just that I use 78 characters instead of 79). But I agree only at the display side, not at the source side. Let me explain Most of the time, I use a folding editor. Not syntax folding, but = user-folding (I use CodeBrowser [from Mark Kerbiquet and for some part m= e = in the past], but I know VIM and Emacs have provisions for the same). = First I feel folding is the biggest thing an editor can offer, far beyon= d = auto-completion and jump-to-declaration or the like features. = Unfortunately, most people open source-files in plain-raw-linear text = editor, without folding. When the source contains nested folders, even i= f = each folder's width is limited to 78 or 79 characters, the plain-text vi= ew = of the text is more than 78 or 79 characters. This simple fact is a real= = brake and refrain the use of folded source for public or other audiance.= = That is why, from time to time, I ask people if they know about more or = = less widely used convention for that or other kind of literate markup in= = source (literate mark up could be used for folding). If there was a = standard markup for that, they would not be any break any more. Plain-linear text is now 60 years old. Isn't time to give a chance to = evolve and get ride of this kind of limitation ? I am not talking about = = RichText editing, =E2=80=A6 just about outlining driven by tiny and simp= le markup = in source comments, and obviously, a standard for that (otherwise it is = = not usable, except for one's-self). P.S. Thanks for the =E2=80=9CShort comments that fit on a single line ar= e NOT = ended with a period.=E2=80=9D in =E2=80=9C3.5 Comment=E2=80=9D : I often= ly had the same question = for myself, and could never make a final decision about it. If you decid= ed = and make it a standard, well, let's go for this one and follow it. P.P.S. No, no, I am not to work on AWS source, I was just reading it = driven by curiosity. :p -- = Si les chats miaulent et font autant de vocalises bizarres, c=E2=80=99es= t pas pour = les chiens. =E2=80=9CI am fluent in ASCII=E2=80=9D [Warren 2010]