From: "Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr>
Subject: AWS Coding Styles (and about boring plain-linear text files in the end)
Date: Mon, 17 Jan 2011 06:07:58 +0100
Date: 2011-01-17T06:07:58+01:00 [thread overview]
Message-ID: <op.vpfsjkfdule2fv@garhos> (raw)
Hi happy night workers,
If ever Pascal or his peer for that project is around the place… 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 “3.5 Comments” :
> 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 “--” ? What could this mean ?
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 ?
In “4 Declarations and Types” :
> 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 “4 Declarations and Types” :
> 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 “6.2 If Statements” :
> 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 “when”
parts of “case” statements ?
Not questions now, personal talks:
In “8 Packages and Visibility Rules” :
> 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 “9 Packages and Visibility Rules” :
> 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… (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
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 me
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 beyond
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 if
each folder's width is limited to 78 or 79 characters, the plain-text view
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, … just about outlining driven by tiny and simple 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 “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.
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’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
next reply other threads:[~2011-01-17 5:07 UTC|newest]
Thread overview: 96+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-01-17 5:07 Yannick Duchêne (Hibou57) [this message]
2011-01-17 5:18 ` AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
2011-01-21 4:06 ` Yannick Duchêne (Hibou57)
2011-01-17 6:43 ` Shark8
2011-01-17 10:22 ` Yannick Duchêne (Hibou57)
2011-01-17 10:23 ` pascal.obry
2011-01-17 10:49 ` Simon Wright
2011-01-17 10:54 ` pascal.obry
2011-01-18 19:07 ` Florian Weimer
2011-01-18 19:47 ` Adam Beneschan
2011-01-18 20:44 ` Florian Weimer
2011-01-18 21:03 ` Adam Beneschan
2011-01-18 22:16 ` Yannick Duchêne (Hibou57)
2011-01-19 6:58 ` Simon Wright
2011-01-19 9:15 ` Yannick Duchêne (Hibou57)
2011-01-19 20:16 ` Simon Wright
2011-01-19 22:42 ` Peter C. Chapin
2011-01-19 22:21 ` Florian Weimer
2011-01-20 1:52 ` Stephen Leake
2011-01-18 20:23 ` Pascal Obry
2011-01-18 21:39 ` Georg Bauhaus
2011-01-18 22:13 ` Randy Brukardt
2011-01-19 0:47 ` Georg Bauhaus
2011-01-19 1:06 ` Yannick Duchêne (Hibou57)
2011-01-19 7:00 ` J-P. Rosen
2011-01-19 8:53 ` Yannick Duchêne (Hibou57)
2011-01-19 10:04 ` Georg Bauhaus
2011-01-19 11:42 ` Yannick Duchêne (Hibou57)
2011-01-19 13:17 ` Georg Bauhaus
2011-01-19 21:56 ` Yannick Duchêne (Hibou57)
2011-01-19 23:34 ` Georg Bauhaus
2011-03-16 18:28 ` Yannick Duchêne (Hibou57)
2011-03-16 20:13 ` Shark8
2011-03-16 21:51 ` Randy Brukardt
2011-03-16 22:01 ` Yannick Duchêne (Hibou57)
2011-03-19 1:47 ` Randy Brukardt
2011-03-16 19:59 ` Yannick Duchêne (Hibou57)
2011-01-18 22:20 ` Yannick Duchêne (Hibou57)
2011-01-18 22:11 ` Yannick Duchêne (Hibou57)
2011-05-25 20:43 ` Yannick Duchêne (Hibou57)
2011-01-17 13:47 ` Bill Findlay
2011-01-17 14:02 ` Yannick Duchêne (Hibou57)
2011-01-17 21:12 ` Simon Wright
2011-01-18 8:03 ` Stephen Leake
2011-01-18 20:41 ` Simon Wright
2011-01-18 0:45 ` Adam Beneschan
2011-01-18 1:40 ` Bill Findlay
2011-01-19 11:12 ` Stephen Leake
2011-01-18 6:07 ` Yannick Duchêne (Hibou57)
2011-01-18 6:07 ` Yannick Duchêne (Hibou57)
2011-01-18 8:04 ` Stephen Leake
2011-01-18 9:11 ` pascal.obry
2011-01-19 11:17 ` Stephen Leake
2011-01-19 11:53 ` Yannick Duchêne (Hibou57)
2011-01-18 8:22 ` Dmitry A. Kazakov
2011-01-18 8:50 ` Georg Bauhaus
2011-01-18 14:20 ` sjw
2011-01-18 15:41 ` Adam Beneschan
2011-01-18 0:58 ` Adam Beneschan
2011-01-18 1:43 ` Bill Findlay
2011-01-18 6:10 ` Yannick Duchêne (Hibou57)
2011-01-18 7:02 ` Pascal Obry
2011-01-18 7:14 ` Thomas Løcke
2011-01-18 7:26 ` Yannick Duchêne (Hibou57)
2011-01-18 12:42 ` Peter C. Chapin
2011-01-18 21:09 ` Yannick Duchêne (Hibou57)
2011-01-18 22:01 ` Randy Brukardt
2011-01-18 22:35 ` Yannick Duchêne (Hibou57)
2011-01-18 23:37 ` tmoran
2011-01-20 2:14 ` Randy Brukardt
2011-01-18 8:06 ` Stephen Leake
2011-01-18 8:54 ` Georg Bauhaus
2011-01-18 15:45 ` Adam Beneschan
2011-01-18 22:03 ` Yannick Duchêne (Hibou57)
2011-01-19 7:19 ` J-P. Rosen
2011-01-19 9:07 ` Yannick Duchêne (Hibou57)
2011-01-19 13:31 ` J-P. Rosen
2011-01-20 1:53 ` Stephen Leake
2011-01-19 9:13 ` Dmitry A. Kazakov
2011-01-19 9:28 ` Yannick Duchêne (Hibou57)
2011-01-19 10:04 ` Dmitry A. Kazakov
2011-01-19 12:16 ` Yannick Duchêne (Hibou57)
2011-01-24 5:13 ` Yannick Duchêne (Hibou57)
2011-01-24 8:29 ` Yannick Duchêne (Hibou57)
2011-01-19 13:39 ` J-P. Rosen
2011-01-19 14:20 ` Dmitry A. Kazakov
2011-01-19 14:52 ` J-P. Rosen
2011-01-19 15:25 ` Dmitry A. Kazakov
2011-01-19 21:43 ` Yannick Duchêne (Hibou57)
2011-01-19 22:20 ` Dmitry A. Kazakov
2011-01-19 21:47 ` Yannick Duchêne (Hibou57)
2011-01-21 19:17 ` Robert Matthews
2011-01-21 19:54 ` Yannick Duchêne (Hibou57)
2011-01-19 18:02 ` Jeffrey Carter
2011-01-19 11:21 ` Stephen Leake
2011-01-19 13:32 ` Yannick Duchêne (Hibou57)
replies disabled
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox