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=ham 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,UTF8 Path: g2news2.google.com!news3.google.com!feeder.news-service.com!85.214.198.2.MISMATCH!eternal-september.org!feeder.eternal-september.org!.POSTED!not-for-mail From: Simon Wright Newsgroups: comp.lang.ada Subject: Re: AWS Coding Styles (and about boring plain-linear text files in the end) Date: Mon, 17 Jan 2011 10:49:28 +0000 Organization: A noiseless patient Spider Message-ID: References: <24418fa4-8843-4fe6-8c2f-026ea6009b68@g26g2000vbz.googlegroups.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: mx02.eternal-september.org; posting-host="dFCm8HWntFqmDIilBLqEJQ"; logging-data="32559"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX19dtNyAIZJrvDpSr7BzKC8AmYScBNWtjWE=" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (darwin) Cancel-Lock: sha1:5bpv9V4T7ILdJZV3AgoR7JvgjSU= sha1:3eYmTjyvuxgmLWKkuuRzpQPUG3I= Xref: g2news2.google.com comp.lang.ada:17448 Date: 2011-01-17T10:49:28+00:00 List-Id: "pascal.obry@gmail.com" writes: > Yannick, >> In “3.5 Comments” : >> >>     > 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 “names of things” 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 I don't disagree (modulo the spelling!), though my problem is whether the comment should go before or after! I know I have some internal rules about this, just never been able to formalise them; 'it just looks right' is hard to explain to others. >> Ah, a big one deal for me this one… (the one which follows) >> >> In “3.1 Character Set and Separators” : >> >>     > 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 > > 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. Reasons for 79: (a) it's what Emacs & GPS do by default (b) it's what the default style checks (-gnaty) enforce. Of course, 78 will also pass the default style checks! >> P.S. Thanks for the “Short comments that fit on a single line are NOT   >> ended with a period.” in “3.5 Comment” : I oftenly had the same question   >> for myself, and could never make a final decision about it. If you decided   >> and make it a standard, well, let's go for this one and follow it. > > This is also GNAT standard. But not, I think, enforced by the style checks? You'd think that if 99 of your subprogram header comments needed >1 line and were ended with periods, you'd to the same for the 1 for consistency.