* AWS Coding Styles (and about boring plain-linear text files in the end)
@ 2011-01-17 5:07 Yannick Duchêne (Hibou57)
2011-01-17 5:18 ` Yannick Duchêne (Hibou57)
` (4 more replies)
0 siblings, 5 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-17 5:07 UTC (permalink / 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]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 5:07 AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
@ 2011-01-17 5:18 ` Yannick Duchêne (Hibou57)
2011-01-21 4:06 ` Yannick Duchêne (Hibou57)
2011-01-17 6:43 ` Shark8
` (3 subsequent siblings)
4 siblings, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-17 5:18 UTC (permalink / raw)
Le Mon, 17 Jan 2011 06:07:58 +0100, Yannick Duchêne (Hibou57)
<yannick_duchene@yahoo.fr> a écrit:
> 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.
Hem, finally no: not good if one want to preserve provision for any kind
of grammatical checker (or any other applications dealing with natural
language in sources). Any way, still thanks, because you helped me to make
a decision ;)
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 5:07 AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
2011-01-17 5:18 ` 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
` (2 subsequent siblings)
4 siblings, 1 reply; 96+ messages in thread
From: Shark8 @ 2011-01-17 6:43 UTC (permalink / raw)
On Jan 16, 10:07 pm, Yannick Duchêne (Hibou57)
<yannick_duch...@yahoo.fr> wrote:
> 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 ?
You'd do that if you're "boxing" in your comments, like so:
------------------------------------------------------
-- This comment describes the key realization for --
-- proving Huffman-encoding as the/a space-optimal --
-- encoding; if two message frequencies are equal --
-- then their encodings may be swiched without any --
-- change to the final length of the encoding. --
------------------------------------------------------
ps, you'll need to use a monospaced font for that to look right.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 6:43 ` Shark8
@ 2011-01-17 10:22 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-17 10:22 UTC (permalink / raw)
Le Mon, 17 Jan 2011 07:43:11 +0100, Shark8 <onewingedshark@gmail.com> a
écrit:
> You'd do that if you're "boxing" in your comments, like so:
> ------------------------------------------------------
> -- This comment describes the key realization for --
> -- proving Huffman-encoding as the/a space-optimal --
> -- encoding; if two message frequencies are equal --
> -- then their encodings may be swiched without any --
> -- change to the final length of the encoding. --
> ------------------------------------------------------
>
> ps, you'll need to use a monospaced font for that to look right.
Yes, of course, the GNAT convention. Silly, I forget it (I do not use it,
this may be why).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 5:07 AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
2011-01-17 5:18 ` Yannick Duchêne (Hibou57)
2011-01-17 6:43 ` Shark8
@ 2011-01-17 10:23 ` pascal.obry
2011-01-17 10:49 ` Simon Wright
` (2 more replies)
2011-01-17 13:47 ` Bill Findlay
2011-01-18 0:58 ` Adam Beneschan
4 siblings, 3 replies; 96+ messages in thread
From: pascal.obry @ 2011-01-17 10:23 UTC (permalink / raw)
Yannick,
> 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 ?
File header (boxed style comment).
> 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
> 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).
I would say that "logical" here cover this case. There is now way
around
that anyway.
> 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).
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 “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 ?
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 “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).
Fine, just another convention.
> 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).
Ok.
> 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.
> 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.
> P.P.S. No, no, I am not to work on AWS source, I was just reading it
> driven by curiosity. :p
:)
Pascal.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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-05-25 20:43 ` Yannick Duchêne (Hibou57)
2 siblings, 1 reply; 96+ messages in thread
From: Simon Wright @ 2011-01-17 10:49 UTC (permalink / raw)
"pascal.obry@gmail.com" <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.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 10:49 ` Simon Wright
@ 2011-01-17 10:54 ` pascal.obry
0 siblings, 0 replies; 96+ messages in thread
From: pascal.obry @ 2011-01-17 10:54 UTC (permalink / raw)
Simon,
> >> 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?
It is not. On my side I'm using Style_Checker (plug plug plug :) to
check this rule
and I have it running into my Git hooks :) So I cannot commit a single
line comment
with dot.
Pascal.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 5:07 AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
` (2 preceding siblings ...)
2011-01-17 10:23 ` pascal.obry
@ 2011-01-17 13:47 ` Bill Findlay
2011-01-17 14:02 ` Yannick Duchêne (Hibou57)
` (2 more replies)
2011-01-18 0:58 ` Adam Beneschan
4 siblings, 3 replies; 96+ messages in thread
From: Bill Findlay @ 2011-01-17 13:47 UTC (permalink / raw)
On 17/01/2011 05:07, in article op.vpfsjkfdule2fv@garhos, "Yannick Duch�ne
(Hibou57)" <yannick_duchene@yahoo.fr> wrote:
> 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).
Why 78/79 and not 80, as I have always used?
Let me guess: badly-implemented terminals/emulators wrap on the 80th
character without checking to see whether it is CR/LF, so you get spurious
double-line spacing if all 80 columns are used?
I follow nearly all of the other guidelines, without having seen
style-guide.html before, so of course, I strongly approve of them. 8-)
FWIW the ones I don't follow are:
> All local subprograms in a subprogram or package body
> should be declared before the first local subprogram
> body.
That seems to me to add pointless verbosity. I declare subprograms iff it is
necessary, and no earlier than necessary.
In �6.2 If Statements� :
> Complex conditions in if-statements are indented two
> characters
I use the same indent (by 3) as for every other nesting (with short-circuit
forms) and no indent if the phrases are parallel (with and/or/xor).
--
Bill Findlay
with blueyonder.co.uk;
use surname & forename;
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 0:45 ` Adam Beneschan
2 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-17 14:02 UTC (permalink / raw)
Le Mon, 17 Jan 2011 14:47:14 +0100, Bill Findlay <news@findlayw.plus.com>
a écrit:
> I use the same indent (by 3) as for every other nesting (with
> short-circuit
> forms) and no indent if the phrases are parallel (with and/or/xor).
The place where I do not use indent, if with When parts of Case.
It appears we all differ in some way, while in the overall, we agree on
most of things. And some point we disagree on, we however probably could
agree to apply without condition because these do not have noticeable
implications (like indent of 2 instead of 3 in some place, required
declaration of subprograms).
That's nice, it appears there is an interesting consensus on this Style
Guide-Lines.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 0:45 ` Adam Beneschan
2 siblings, 1 reply; 96+ messages in thread
From: Simon Wright @ 2011-01-17 21:12 UTC (permalink / raw)
Bill Findlay <news@findlayw.plus.com> writes:
> In ³6.2 If Statements² :
>
> > Complex conditions in if-statements are indented two
> > characters
>
> I use the same indent (by 3) as for every other nesting (with
> short-circuit forms) and no indent if the phrases are parallel (with
> and/or/xor).
I don't know what Emacs ada-mode indents by, I just let it have its way!
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 0:45 ` Adam Beneschan
2011-01-18 1:40 ` Bill Findlay
` (5 more replies)
2 siblings, 6 replies; 96+ messages in thread
From: Adam Beneschan @ 2011-01-18 0:45 UTC (permalink / raw)
On Jan 17, 5:47 am, Bill Findlay <n...@findlayw.plus.com> wrote:
> >> 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).
>
> Why 78/79 and not 80, as I have always used?
I tend to make all my windows 80 characters wide. I use EMACS, which
reserves the 80th character for a wrapping indicator, so that if you
used it on a source with an 80-character line, EMACS would display
only 79 of those on the first line, put a mark in the 80th character
indicating that the line is wrapped, and then display the 80th
character on the next line.
-- Adam
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 5:07 AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
` (3 preceding siblings ...)
2011-01-17 13:47 ` Bill Findlay
@ 2011-01-18 0:58 ` Adam Beneschan
2011-01-18 1:43 ` Bill Findlay
` (3 more replies)
4 siblings, 4 replies; 96+ messages in thread
From: Adam Beneschan @ 2011-01-18 0:58 UTC (permalink / raw)
On Jan 16, 9:07 pm, Yannick Duchêne (Hibou57)
<yannick_duch...@yahoo.fr> wrote:
> 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).
My preference is to say "with Ada.Strings;", even if I am also
with'ing Ada.Strings.Unbounded, if (and only if) I am referring to
something actually declared in Ada.Strings (such as
Ada.Strings.Direction). I think that makes things clearer. I can't
really imagine why anyone would think it's a bad idea to say "with
Ada.Strings;" in that case.
Then again, I've never had much use for style guides, especially when
they're enforced. I think I do a good job of being sensitive to
others who might read my source, and writing in a way that makes it
easier on them; sometimes strict rules can actually prevent me from
doing the best job of this, especially since the one who writes the
rules may not have thought about every possible circumstance.
-- Adam
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
` (4 subsequent siblings)
5 siblings, 1 reply; 96+ messages in thread
From: Bill Findlay @ 2011-01-18 1:40 UTC (permalink / raw)
On 18/01/2011 00:45, in article
a4cd6433-57ed-49ae-9d30-4f358c28caac@m20g2000prc.googlegroups.com, "Adam
Beneschan" <adam@irvine.com> wrote:
> On Jan 17, 5:47�am, Bill Findlay <n...@findlayw.plus.com> wrote:
>
>>>> 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).
>>
>> Why 78/79 and not 80, as I have always used?
>
> I tend to make all my windows 80 characters wide. I use EMACS, which
> reserves the 80th character for a wrapping indicator, so that if you
> used it on a source with an 80-character line, EMACS would display
> only 79 of those on the first line, put a mark in the 80th character
> indicating that the line is wrapped, and then display the 80th
> character on the next line.
Ah, EMACS: 1970s software that's as bad as 1970s terminal hardware!
That explains it. I feel so avant-garde, being able to edit all 80
columns of a card image without such problems. 8-)
--
Bill Findlay
with blueyonder.co.uk;
use surname & forename;
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:58 ` Adam Beneschan
@ 2011-01-18 1:43 ` Bill Findlay
2011-01-18 6:10 ` Yannick Duchêne (Hibou57)
` (2 subsequent siblings)
3 siblings, 0 replies; 96+ messages in thread
From: Bill Findlay @ 2011-01-18 1:43 UTC (permalink / raw)
On 18/01/2011 00:58, in article
3077fffa-eed7-4763-8bca-9ac3bb0a41e1@o14g2000prn.googlegroups.com, "Adam
Beneschan" <adam@irvine.com> wrote:
> Then again, I've never had much use for style guides, especially when
> they're enforced. I think I do a good job of being sensitive to
> others who might read my source, and writing in a way that makes it
> easier on them; sometimes strict rules can actually prevent me from
> doing the best job of this, especially since the one who writes the
> rules may not have thought about every possible circumstance.
I absolutely agree with this.
--
Bill Findlay
with blueyonder.co.uk;
use surname & forename;
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:45 ` Adam Beneschan
2011-01-18 1:40 ` Bill Findlay
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
` (2 subsequent siblings)
5 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 6:07 UTC (permalink / raw)
Le Tue, 18 Jan 2011 01:45:16 +0100, Adam Beneschan <adam@irvine.com> a
écrit:
> On Jan 17, 5:47 am, Bill Findlay <n...@findlayw.plus.com> wrote:
>
>> >> 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).
>>
>> Why 78/79 and not 80, as I have always used?
>
> I tend to make all my windows 80 characters wide. I use EMACS, which
> reserves the 80th character for a wrapping indicator, so that if you
> used it on a source with an 80-character line, EMACS would display
> only 79 of those on the first line, put a mark in the 80th character
> indicating that the line is wrapped, and then display the 80th
> character on the next line.
Alternatively, on 80 characters wide terminal, an editor may draw a frame,
consuming one character on the left edge and one character the right edge
(think about the EDIT.COM program coming with MS-DOS).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:45 ` Adam Beneschan
2011-01-18 1:40 ` Bill Findlay
@ 2011-01-18 6:07 ` Yannick Duchêne (Hibou57)
2011-01-18 6:07 ` Yannick Duchêne (Hibou57)
` (3 subsequent siblings)
5 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 6:07 UTC (permalink / raw)
Le Tue, 18 Jan 2011 01:45:16 +0100, Adam Beneschan <adam@irvine.com> a
écrit:
> On Jan 17, 5:47 am, Bill Findlay <n...@findlayw.plus.com> wrote:
>
>> >> 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).
>>
>> Why 78/79 and not 80, as I have always used?
>
> I tend to make all my windows 80 characters wide. I use EMACS, which
> reserves the 80th character for a wrapping indicator, so that if you
> used it on a source with an 80-character line, EMACS would display
> only 79 of those on the first line, put a mark in the 80th character
> indicating that the line is wrapped, and then display the 80th
> character on the next line.
Alternatively, on 80 characters wide terminal, an editor may draw a frame,
consuming one character on the left edge and one character the right edge
(think about the EDIT.COM program coming with MS-DOS).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 8:06 ` Stephen Leake
3 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 6:10 UTC (permalink / raw)
Le Tue, 18 Jan 2011 01:58:31 +0100, Adam Beneschan <adam@irvine.com> a
écrit:
> On Jan 16, 9:07 pm, Yannick Duchêne (Hibou57)
> <yannick_duch...@yahoo.fr> wrote:
>
>> 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).
>
> My preference is to say "with Ada.Strings;", even if I am also
> with'ing Ada.Strings.Unbounded, if (and only if) I am referring to
> something actually declared in Ada.Strings (such as
> Ada.Strings.Direction). I think that makes things clearer. I can't
> really imagine why anyone would think it's a bad idea to say "with
> Ada.Strings;" in that case.
That is indeed what I was trying to explain.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
` (2 more replies)
2011-01-18 8:06 ` Stephen Leake
3 siblings, 3 replies; 96+ messages in thread
From: Pascal Obry @ 2011-01-18 7:02 UTC (permalink / raw)
To: Adam Beneschan
Adam,
> Then again, I've never had much use for style guides, especially when
> they're enforced. I think I do a good job of being sensitive to
> others who might read my source, and writing in a way that makes it
> easier on them; sometimes strict rules can actually prevent me from
> doing the best job of this, especially since the one who writes the
> rules may not have thought about every possible circumstance.
In contrary, I do like very much style guide for at least one reason.
When you work in with a group of developer no one should own somehow a
bit of code. A uniform indentation avoids : "this is my code", "this is
joe part"... Everybody on the team should feel comfortable with the
whole software. The style is not that important, but a single style
across a project is if you ask me.
Pascal.
--
--|------------------------------------------------------
--| Pascal Obry Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--| http://www.obry.net - http://v2p.fr.eu.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver keys.gnupg.net --recv-key F949BD3B
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
2 siblings, 0 replies; 96+ messages in thread
From: Thomas Løcke @ 2011-01-18 7:14 UTC (permalink / raw)
On 2011-01-18 08:02, Pascal Obry wrote:
> In contrary, I do like very much style guide for at least one reason.
> When you work in with a group of developer no one should own somehow a
> bit of code. A uniform indentation avoids : "this is my code", "this is
> joe part"... Everybody on the team should feel comfortable with the
> whole software. The style is not that important, but a single style
> across a project is if you ask me.
That is also my experience. I did a +100_000 LOC PHP project some years
ago with some friends of mine, and we _very_ quickly realized we had to
come up with some sort of common style guide, if we were to avoid ending
up with source files that were done in completely different styles.
--
Regards,
Thomas L�cke
Email: tl at ada-dk.org
Web: http//:ada-dk.org
http://identi.ca/thomaslocke
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
2 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 7:26 UTC (permalink / raw)
Le Tue, 18 Jan 2011 08:02:58 +0100, Pascal Obry <pascal@obry.net> a écrit:
>> Then again, I've never had much use for style guides, especially when
>> they're enforced. I think I do a good job of being sensitive to
>> others who might read my source, and writing in a way that makes it
>> easier on them; sometimes strict rules can actually prevent me from
>> doing the best job of this, especially since the one who writes the
>> rules may not have thought about every possible circumstance.
>
> In contrary, I do like very much style guide for at least one reason.
> When you work in with a group of developer no one should own somehow a
> bit of code. A uniform indentation avoids : "this is my code", "this is
> joe part"... Everybody on the team should feel comfortable with the
> whole software. The style is not that important, but a single style
> across a project is if you ask me.
Good points and well justified (will note it in my mind).
And on my side, I feel guide-lines documentations comes as natural with
design documentation (as part of it). It is also one of the easiest to
start with when you at least want to give a seed to such documentation.
This may also be a sign the author(s) cared ;) If I was to rate projects,
this would be a constant criteria and I would give or retain some points
based on the presence or absence of such documentation.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 21:12 ` Simon Wright
@ 2011-01-18 8:03 ` Stephen Leake
2011-01-18 20:41 ` Simon Wright
0 siblings, 1 reply; 96+ messages in thread
From: Stephen Leake @ 2011-01-18 8:03 UTC (permalink / raw)
Simon Wright <simon@pushface.org> writes:
> Bill Findlay <news@findlayw.plus.com> writes:
>
>> In ³6.2 If Statements² :
>>
>> > Complex conditions in if-statements are indented two
>> > characters
>>
>> I use the same indent (by 3) as for every other nesting (with
>> short-circuit forms) and no indent if the phrases are parallel (with
>> and/or/xor).
>
> I don't know what Emacs ada-mode indents by, I just let it have its way!
That is fully customizable.
My main style rule is "whatever Emacs does (with our customizations) is
right". That saves lots of time :).
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:45 ` Adam Beneschan
` (2 preceding siblings ...)
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-18 8:22 ` Dmitry A. Kazakov
2011-01-18 8:50 ` Georg Bauhaus
5 siblings, 1 reply; 96+ messages in thread
From: Stephen Leake @ 2011-01-18 8:04 UTC (permalink / raw)
Adam Beneschan <adam@irvine.com> writes:
> On Jan 17, 5:47 am, Bill Findlay <n...@findlayw.plus.com> wrote:
>
>> >> 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).
>>
>> Why 78/79 and not 80, as I have always used?
>
> I tend to make all my windows 80 characters wide. I use EMACS, which
> reserves the 80th character for a wrapping indicator, so that if you
> used it on a source with an 80-character line, EMACS would display
> only 79 of those on the first line, put a mark in the 80th character
> indicating that the line is wrapped, and then display the 80th
> character on the next line.
Note that on a GUI display, the "wrapping mark" is in the margin, not in
the text area.
I use 120 character text areas; much more readable with reasonable name
lengths.
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:58 ` Adam Beneschan
` (2 preceding siblings ...)
2011-01-18 7:02 ` Pascal Obry
@ 2011-01-18 8:06 ` Stephen Leake
2011-01-18 8:54 ` Georg Bauhaus
3 siblings, 1 reply; 96+ messages in thread
From: Stephen Leake @ 2011-01-18 8:06 UTC (permalink / raw)
Adam Beneschan <adam@irvine.com> writes:
> Then again, I've never had much use for style guides, especially when
> they're enforced.
I mostly find them useful to settle style arguments; "we do it this way
because we agreed to".
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:45 ` Adam Beneschan
` (3 preceding siblings ...)
2011-01-18 8:04 ` Stephen Leake
@ 2011-01-18 8:22 ` Dmitry A. Kazakov
2011-01-18 8:50 ` Georg Bauhaus
5 siblings, 0 replies; 96+ messages in thread
From: Dmitry A. Kazakov @ 2011-01-18 8:22 UTC (permalink / raw)
On Mon, 17 Jan 2011 16:45:16 -0800 (PST), Adam Beneschan wrote:
> On Jan 17, 5:47�am, Bill Findlay <n...@findlayw.plus.com> wrote:
>
>>>> 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).
>>
>> Why 78/79 and not 80, as I have always used?
>
> I tend to make all my windows 80 characters wide.
72! The positions 73..80 are reserved the punched card number.
--
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 0:45 ` Adam Beneschan
` (4 preceding siblings ...)
2011-01-18 8:22 ` Dmitry A. Kazakov
@ 2011-01-18 8:50 ` Georg Bauhaus
2011-01-18 14:20 ` sjw
5 siblings, 1 reply; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-18 8:50 UTC (permalink / raw)
On 1/18/11 1:45 AM, Adam Beneschan wrote:
> On Jan 17, 5:47 am, Bill Findlay<n...@findlayw.plus.com> wrote:
>
>>>> 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).
>>
>> Why 78/79 and not 80, as I have always used?
>
> I tend to make all my windows 80 characters wide. I use EMACS, which
> reserves the 80th character for a wrapping indicator, so that if you
> used it on a source with an 80-character line, EMACS would display
> only 79 of those on the first line, put a mark in the 80th character
> indicating that the line is wrapped, and then display the 80th
> character on the next line.
Emacs seems to be off by 1, then ;-) To edit a card image (an
instructive idea!) I'd toggle-truncate-lines and then
set-variable hscroll-margin to 1 (or 0). Unfortunately, this
hides the 80th character behind the truncation indicator $. I
cannot believe that an editor capable of patching binary files
and viper-mode forces display of a useless EOL character? OTOH,
it is written in C...
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 8:06 ` Stephen Leake
@ 2011-01-18 8:54 ` Georg Bauhaus
2011-01-18 15:45 ` Adam Beneschan
0 siblings, 1 reply; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-18 8:54 UTC (permalink / raw)
On 1/18/11 9:06 AM, Stephen Leake wrote:
> Adam Beneschan<adam@irvine.com> writes:
>
>> Then again, I've never had much use for style guides, especially when
>> they're enforced.
>
> I mostly find them useful to settle style arguments; "we do it this way
> because we agreed to".
If "we don't agree", a more flexible setting would be to
have a computer adapt the display style of a free-format
language program to each one's viewing preferences...
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 8:04 ` Stephen Leake
@ 2011-01-18 9:11 ` pascal.obry
2011-01-19 11:17 ` Stephen Leake
0 siblings, 1 reply; 96+ messages in thread
From: pascal.obry @ 2011-01-18 9:11 UTC (permalink / raw)
On Jan 18, 9:04 am, Stephen Leake <stephen_le...@stephe-leake.org>
wrote:
> I use 120 character text areas; much more readable with reasonable name
> lengths.
But hard to read a diff and almost impossible to have a side by side
view
to resolve merge conflicts (with meld, diffuse...)
Newspaper have short lines to help read fast. Longer the line is,
harder it
is to go back to the next line.
Pascal.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
2 siblings, 1 reply; 96+ messages in thread
From: Peter C. Chapin @ 2011-01-18 12:42 UTC (permalink / raw)
On 2011-01-18 02:02, Pascal Obry wrote:
> In contrary, I do like very much style guide for at least one reason.
> When you work in with a group of developer no one should own somehow a
> bit of code. A uniform indentation avoids : "this is my code", "this is
> joe part"... Everybody on the team should feel comfortable with the
> whole software. The style is not that important, but a single style
> across a project is if you ask me.
I want to echo my agreement with this. I'm working on a project with
several students, most of whom are fairly inexperienced. Having a common
style is very helpful. Instead of brow beating the students into a
particular style we've agreed to just follow what gnatpp does. We can
agree on a particular configuration of the pretty printer and then
everyone can conform to the project specified style by just pressing a
button in GPS. No arguments.
I agree with Adam that sometimes the results are less than optimal and
certainly not as good as *I* would do on my own. :) Yet having an
enforced style that can be easily applied with the help of a tool has
made the code base better overall.
Peter
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 8:50 ` Georg Bauhaus
@ 2011-01-18 14:20 ` sjw
2011-01-18 15:41 ` Adam Beneschan
0 siblings, 1 reply; 96+ messages in thread
From: sjw @ 2011-01-18 14:20 UTC (permalink / raw)
On Jan 18, 8:50 am, Georg Bauhaus <rm-host.bauh...@maps.futureapps.de>
wrote:
> On 1/18/11 1:45 AM, Adam Beneschan wrote:
>
>
>
> > On Jan 17, 5:47 am, Bill Findlay<n...@findlayw.plus.com> wrote:
>
> >>>> 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).
>
> >> Why 78/79 and not 80, as I have always used?
>
> > I tend to make all my windows 80 characters wide. I use EMACS, which
> > reserves the 80th character for a wrapping indicator, so that if you
> > used it on a source with an 80-character line, EMACS would display
> > only 79 of those on the first line, put a mark in the 80th character
> > indicating that the line is wrapped, and then display the 80th
> > character on the next line.
>
> Emacs seems to be off by 1, then ;-) To edit a card image (an
> instructive idea!) I'd toggle-truncate-lines and then
> set-variable hscroll-margin to 1 (or 0). Unfortunately, this
> hides the 80th character behind the truncation indicator $. I
> cannot believe that an editor capable of patching binary files
> and viper-mode forces display of a useless EOL character? OTOH,
> it is written in C...
Might make sense, alternatively, to make the window 81 columns wide ..
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 14:20 ` sjw
@ 2011-01-18 15:41 ` Adam Beneschan
0 siblings, 0 replies; 96+ messages in thread
From: Adam Beneschan @ 2011-01-18 15:41 UTC (permalink / raw)
On Jan 18, 6:20 am, sjw <simon.j.wri...@mac.com> wrote:
> On Jan 18, 8:50 am, Georg Bauhaus <rm-host.bauh...@maps.futureapps.de>
> wrote:
>
>
>
>
>
> > On 1/18/11 1:45 AM, Adam Beneschan wrote:
>
> > > On Jan 17, 5:47 am, Bill Findlay<n...@findlayw.plus.com> wrote:
>
> > >>>> 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).
>
> > >> Why 78/79 and not 80, as I have always used?
>
> > > I tend to make all my windows 80 characters wide. I use EMACS, which
> > > reserves the 80th character for a wrapping indicator, so that if you
> > > used it on a source with an 80-character line, EMACS would display
> > > only 79 of those on the first line, put a mark in the 80th character
> > > indicating that the line is wrapped, and then display the 80th
> > > character on the next line.
>
> > Emacs seems to be off by 1, then ;-) To edit a card image (an
> > instructive idea!) I'd toggle-truncate-lines and then
> > set-variable hscroll-margin to 1 (or 0). Unfortunately, this
> > hides the 80th character behind the truncation indicator $. I
> > cannot believe that an editor capable of patching binary files
> > and viper-mode forces display of a useless EOL character? OTOH,
> > it is written in C...
>
> Might make sense, alternatively, to make the window 81 columns wide ..
I know, I know. I don't really have a good reason for how I do
things, just tradition, I guess (although I tend to go along with
Pascal's reasons for not having windows *too* wide). But I'm guessing
I'm not the only one who adheres to this tradition. I'm just offering
this as a possible reason why a style guide author might have
suggested a 79-character width instead of 80.
-- Adam
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 8:54 ` Georg Bauhaus
@ 2011-01-18 15:45 ` Adam Beneschan
2011-01-18 22:03 ` Yannick Duchêne (Hibou57)
0 siblings, 1 reply; 96+ messages in thread
From: Adam Beneschan @ 2011-01-18 15:45 UTC (permalink / raw)
On Jan 18, 12:54 am, Georg Bauhaus <rm-
host.bauh...@maps.futureapps.de> wrote:
> On 1/18/11 9:06 AM, Stephen Leake wrote:
>
> > Adam Beneschan<a...@irvine.com> writes:
>
> >> Then again, I've never had much use for style guides, especially when
> >> they're enforced.
>
> > I mostly find them useful to settle style arguments; "we do it this way
> > because we agreed to".
>
> If "we don't agree", a more flexible setting would be to
> have a computer adapt the display style of a free-format
> language program to each one's viewing preferences...
Good point. This is the 21st century, technology has advanced to the
point where it shouldn't be difficult to do this. Of course, maybe
that case should be made by someone who isn't using a 1970s editor and
sticking to a traditional line width based on punch cards. :) :)
-- Adam
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 10:23 ` pascal.obry
2011-01-17 10:49 ` Simon Wright
@ 2011-01-18 19:07 ` Florian Weimer
2011-01-18 19:47 ` Adam Beneschan
` (2 more replies)
2011-05-25 20:43 ` Yannick Duchêne (Hibou57)
2 siblings, 3 replies; 96+ messages in thread
From: Florian Weimer @ 2011-01-18 19:07 UTC (permalink / raw)
* pascal:
>> > 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
The problem is that the rule is self-contradictory. I think it should
say, "should not specifically mention", i.e., the opposite of what you
suggested.
I will submit a patch to gcc/ada/gnat-style.texi to fix this.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 19:07 ` Florian Weimer
@ 2011-01-18 19:47 ` Adam Beneschan
2011-01-18 20:44 ` Florian Weimer
2011-01-18 22:16 ` Yannick Duchêne (Hibou57)
2011-01-18 20:23 ` Pascal Obry
2011-01-18 22:11 ` Yannick Duchêne (Hibou57)
2 siblings, 2 replies; 96+ messages in thread
From: Adam Beneschan @ 2011-01-18 19:47 UTC (permalink / raw)
On Jan 18, 11:07 am, Florian Weimer <f...@deneb.enyo.de> wrote:
> * pascal:
>
>
>
>
>
> >> > 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
>
> The problem is that the rule is self-contradictory. I think it should
> say, "should not specifically mention", i.e., the opposite of what you
> suggested.
Maybe that's what the style guide author intended. If so, I think he
had it completely backward. Look at the RM's descriptions of what the
subprograms in language-defined packages do, and then try to figure
out how to describe them without referring to parameter names. Try
Ada.Strings.Unbounded.To_String and To_Unbounded_String, for example,
in A.4.5(78-79). That's just the first thing I went to when I picked
an Annex A section more or less arbitrarily---I didn't have to hunt
for the "best example". Anyway, you *could* rewrite the description
in a way that doesn't refer to the parameter names, but all you gain
is verbosity and stilted-sounding language---at the expense of
clarity, readability, and several dozen of your readers' brain cells.
In fact, the RM does this quite consistently, which would make it a
bit odd for a style guide to decide on a "rule" that is exactly the
opposite. So maybe your suggested fix for this contradiction is the
opposite of what was intended.
-- Adam
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 19:07 ` Florian Weimer
2011-01-18 19:47 ` Adam Beneschan
@ 2011-01-18 20:23 ` Pascal Obry
2011-01-18 21:39 ` Georg Bauhaus
2011-01-18 22:20 ` Yannick Duchêne (Hibou57)
2011-01-18 22:11 ` Yannick Duchêne (Hibou57)
2 siblings, 2 replies; 96+ messages in thread
From: Pascal Obry @ 2011-01-18 20:23 UTC (permalink / raw)
To: Florian Weimer
Florian,
> The problem is that the rule is self-contradictory. I think it should
> say, "should not specifically mention", i.e., the opposite of what you
> suggested.
No, it is definitely "should specifically mention". We are talking about
the formal name here. Please reread my response to Yannick about this one.
--
--|------------------------------------------------------
--| Pascal Obry Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--| http://www.obry.net - http://v2p.fr.eu.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver keys.gnupg.net --recv-key F949BD3B
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 8:03 ` Stephen Leake
@ 2011-01-18 20:41 ` Simon Wright
0 siblings, 0 replies; 96+ messages in thread
From: Simon Wright @ 2011-01-18 20:41 UTC (permalink / raw)
Stephen Leake <stephen_leake@stephe-leake.org> writes:
> Simon Wright <simon@pushface.org> writes:
>> I don't know what Emacs ada-mode indents by, I just let it have its
>> way!
>
> That is fully customizable.
>
> My main style rule is "whatever Emacs does (with our customizations)
> is right". That saves lots of time :).
And you can save a few seconds more by just taking the customisations
that your supplier set, if they're generally OK. I like how emacs
ada-mode is set up... which turns out unsurprisingly to be the way GPS
works, too. There may of course be some odd corner cases of difference.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
1 sibling, 1 reply; 96+ messages in thread
From: Florian Weimer @ 2011-01-18 20:44 UTC (permalink / raw)
* Adam Beneschan:
> Maybe that's what the style guide author intended. If so, I think he
> had it completely backward. Look at the RM's descriptions of what the
> subprograms in language-defined packages do, and then try to figure
> out how to describe them without referring to parameter names. Try
> Ada.Strings.Unbounded.To_String and To_Unbounded_String, for example,
> in A.4.5(78-79). That's just the first thing I went to when I picked
> an Annex A section more or less arbitrarily---I didn't have to hunt
> for the "best example". Anyway, you *could* rewrite the description
> in a way that doesn't refer to the parameter names, but all you gain
> is verbosity and stilted-sounding language---at the expense of
> clarity, readability, and several dozen of your readers' brain cells.
Huh?
In my version, I've got:
| 9
| function To_Unbounded_String (Source : in String)
| return Unbounded_String;
| 11
| function To_String (Source : in Unbounded_String) return String;
| 78
| * If S is a String, then To_String(To_Unbounded_String(S)) = S.
|
| 79
| * If U is an Unbounded_String, then
| To_Unbounded_String(To_String(U)) = U.
|
So this description does not use the formal parameter names at all!
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 20:44 ` Florian Weimer
@ 2011-01-18 21:03 ` Adam Beneschan
0 siblings, 0 replies; 96+ messages in thread
From: Adam Beneschan @ 2011-01-18 21:03 UTC (permalink / raw)
On Jan 18, 12:44 pm, Florian Weimer <f...@deneb.enyo.de> wrote:
> * Adam Beneschan:
>
> > Maybe that's what the style guide author intended. If so, I think he
> > had it completely backward. Look at the RM's descriptions of what the
> > subprograms in language-defined packages do, and then try to figure
> > out how to describe them without referring to parameter names. Try
> > Ada.Strings.Unbounded.To_String and To_Unbounded_String, for example,
> > in A.4.5(78-79). That's just the first thing I went to when I picked
> > an Annex A section more or less arbitrarily---I didn't have to hunt
> > for the "best example". Anyway, you *could* rewrite the description
> > in a way that doesn't refer to the parameter names, but all you gain
> > is verbosity and stilted-sounding language---at the expense of
> > clarity, readability, and several dozen of your readers' brain cells.
>
> Huh?
>
> In my version, I've got:
>
> | 9
> | function To_Unbounded_String (Source : in String)
> | return Unbounded_String;
> | 11
> | function To_String (Source : in Unbounded_String) return String;
>
> | 78
> | * If S is a String, then To_String(To_Unbounded_String(S)) = S.
> |
> | 79
> | * If U is an Unbounded_String, then
> | To_Unbounded_String(To_String(U)) = U.
> |
>
> So this description does not use the formal parameter names at all!
Son of a (*&#$(*&, I found the one section of A.4.5 that used names
other than the formal parameter names. [Note that it doesn't try to
use English text instead of the formal names, but rather substitutes
its own algebra-like variable name.]
OK, then, look at most of the rest of A.4.5, or A.16, or A.10.5 other
than the File parameter.
But I'll take back one thing I said---the RM isn't as consistent as I
thought. 11.4.1 seems to avoid using formal parameter names. In 3.9,
it looks as though the pre-Ada 2005 material tried to avoid using
formal parameter names, but subprogram descriptions added later did
not.
I'll stand by most of what I said, though. Much or most of the RM
uses formal parameter names in the descriptions, and I believe that
avoiding formal parameter names gains nothing and often loses.
-- Adam
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 12:42 ` Peter C. Chapin
@ 2011-01-18 21:09 ` Yannick Duchêne (Hibou57)
2011-01-18 22:01 ` Randy Brukardt
0 siblings, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 21:09 UTC (permalink / raw)
Le Tue, 18 Jan 2011 13:42:55 +0100, Peter C. Chapin <PChapin@vtc.vsc.edu>
a écrit:
> particular style we've agreed to just follow what gnatpp does.
> ...
> I agree with Adam that sometimes the results are less than optimal and
> certainly not as good as *I* would do on my own. :)
I've noticed sometime GNATPP formating is ugly, especially with renaming
declarations (automated pretty-printing is not as easy as it may looks to
be).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 20:23 ` Pascal Obry
@ 2011-01-18 21:39 ` Georg Bauhaus
2011-01-18 22:13 ` Randy Brukardt
2011-01-18 22:20 ` Yannick Duchêne (Hibou57)
1 sibling, 1 reply; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-18 21:39 UTC (permalink / raw)
On 18.01.11 21:23, Pascal Obry wrote:
>
> Florian,
>
>> The problem is that the rule is self-contradictory. I think it should
>> say, "should not specifically mention", i.e., the opposite of what you
>> suggested.
>
> No, it is definitely "should specifically mention". We are talking about
> the formal name here. Please reread my response to Yannick about this one.
>
The trouble here is maybe that the guidelines say
1) Mention the formal argument names!
2) Do not depend on the names of things!
I first thought of the distinction between "to mention" and
"to use" and how it is usually found confusing and thus
frequently accompanied by a definition. Which one is appropriate here?
Second, the style rule requires thinking about an apparent
contradiction, created by a certain reading of (2) in the
presence of (1). The reader assigns possibly unintended,
yet plausible, meaning to the words "depend" and "names",
and concludes:
"How is one to mention formal argument names in a comment
but such that one must not depend on names in the comment?"
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
0 siblings, 2 replies; 96+ messages in thread
From: Randy Brukardt @ 2011-01-18 22:01 UTC (permalink / raw)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1259 bytes --]
"Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> wrote in message
news:op.vpivpijoule2fv@garhos...
Le Tue, 18 Jan 2011 13:42:55 +0100, Peter C. Chapin <PChapin@vtc.vsc.edu>
a �crit:
>> particular style we've agreed to just follow what gnatpp does.
>> ...
>> I agree with Adam that sometimes the results are less than optimal and
>> certainly not as good as *I* would do on my own. :)
>I've noticed sometime GNATPP formating is ugly, especially with renaming
>declarations (automated pretty-printing is not as easy as it may looks to
>be).
I'll second that. We created a pretty-printer for Janus/Ada years ago with
the idea of using it to put all of our code into a common style. The results
were not very pleasing and we never ended up using it. We still provide it
to customers, but I don't think many are using it, as I've not had much luck
using it. Once (not that long ago) I found that it made a complete mess out
of task type declarations - it turned out they'd never been implemented at
all. You'd think someone would report such things if they cared...
Randy.
--
Si les chats miaulent et font autant de vocalises bizarres, c'est pas pour
les chiens.
"I am fluent in ASCII" [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 11:21 ` Stephen Leake
0 siblings, 2 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 22:03 UTC (permalink / raw)
Le Tue, 18 Jan 2011 16:45:42 +0100, Adam Beneschan <adam@irvine.com> a
écrit:
> Good point. This is the 21st century, technology has advanced to the
> point where it shouldn't be difficult to do this. Of course, maybe
> that case should be made by someone who isn't using a 1970s editor and
> sticking to a traditional line width based on punch cards. :) :)
Just wanted to underline again what Pascal Obry also said (and I fully
agree with, and others too) : the line length limitation is not due to any
inheritance from old and obsolete systems, this has ergonomic motivations.
He pointed the example of news-paper. The typical width of a news paper or
magazine text is even lower : 40 or 50 characters width is a common
layout. If you doubt, then a question : where do you think these old
systems get this default screen width of 80 characters ? You think they
were not able to do it wider ? Answer : from the ergonomic principle
stated above. 80 characters width was not due to technical limitations,
this was a target specification.
Now, to go further: terminal may also be used to draw nice text-UI
(especially with colored terminals). In this context, 80 characters is not
enough, because then the UI eats on the width which is expected to be
available for the text. To ease text UI, there use to be wider standard
(120 characters if my mind is right, 120 characters is really better for a
MidnightCommander). Also about the 40 or 50 characters of typical
newspapers and magazines: the width used in miscellaneous computer source
texts (C, SGML, FORTRAN), was larger I suppose for the requirement of
indentations, which also eats on the text width too. Then, there is the
reason of longer word in typical computer texts, because these are longer
composite word, with no space (i.e. “This unavoidable object” vs
“This_Unavoidable_Object”).
If there is an area where we still unfortunately stick to old obsolete
systems, the is not about text width, this about two other points: 1)
ASCII heritage vs Unicode (using either Emacs or VIM for multi-language
text files is simply *impossible* most of the time, while OTH, the basic
NotePad of Windows 98 is perfectly able in this area). 2) Raw linear text
(this gonna be the subject of a coming topic I will later opened, coming
in a few days… I've not yet finished to write it).
With these two points, and especially the second (the first slowly evolve,
except with some old editors), we, indeed are really sticked in the past;
not with line length which must be limited.
However, your comment makes me think about another argument for the topic
I will open a later day. Thanks for that.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 19:07 ` Florian Weimer
2011-01-18 19:47 ` Adam Beneschan
2011-01-18 20:23 ` Pascal Obry
@ 2011-01-18 22:11 ` Yannick Duchêne (Hibou57)
2 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 22:11 UTC (permalink / raw)
Le Tue, 18 Jan 2011 20:07:20 +0100, Florian Weimer <fw@deneb.enyo.de> a
écrit:
> * pascal:
>
>>> > 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
>
> The problem is that the rule is self-contradictory. I think it should
> say, "should not specifically mention", i.e., the opposite of what you
> suggested.
>
> I will submit a patch to gcc/ada/gnat-style.texi to fix this.
Thanks, that's crystal-clear now. Just that we may wait for a confirmation
from Pascal (if ever this interpretation is also wrong).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 21:39 ` Georg Bauhaus
@ 2011-01-18 22:13 ` Randy Brukardt
2011-01-19 0:47 ` Georg Bauhaus
0 siblings, 1 reply; 96+ messages in thread
From: Randy Brukardt @ 2011-01-18 22:13 UTC (permalink / raw)
"Georg Bauhaus" <rm.dash-bauhaus@futureapps.de> wrote in message
news:4d3608ab$0$7664$9b4e6d93@newsspool1.arcor-online.net...
> On 18.01.11 21:23, Pascal Obry wrote:
>>
>> Florian,
>>
>>> The problem is that the rule is self-contradictory. I think it should
>>> say, "should not specifically mention", i.e., the opposite of what you
>>> suggested.
>>
>> No, it is definitely "should specifically mention". We are talking about
>> the formal name here. Please reread my response to Yannick about this
>> one.
>>
>
> The trouble here is maybe that the guidelines say
>
> 1) Mention the formal argument names!
>
> 2) Do not depend on the names of things!
>
> I first thought of the distinction between "to mention" and
> "to use" and how it is usually found confusing and thus
> frequently accompanied by a definition. Which one is appropriate here?
>
> Second, the style rule requires thinking about an apparent
> contradiction, created by a certain reading of (2) in the
> presence of (1). The reader assigns possibly unintended,
> yet plausible, meaning to the words "depend" and "names",
> and concludes:
>
> "How is one to mention formal argument names in a comment
> but such that one must not depend on names in the comment?"
I agree. (I'm working on the Ada standard right now, so I'm reading things
fairly formally.) Indeed, I still have no idea what the second sentence of
that style section is supposed to mean. I thought it meant the exact
opposite of the first sentence (with which I agree wholeheartedly) -- the
only way *not* to depend on the names is to not include them in the text.
I'd probably suggest dropping it altogether -- I have no idea how to write a
useful comment that doesn't depend on the names of things.
Perhaps the point was that there always should be a comment (rather than
expecting the name of the parameters to serve in place of a comment) -- in
that case, the text needs to emphasize the need for comments rather than the
reason for omitting them.
Randy.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 19:47 ` Adam Beneschan
2011-01-18 20:44 ` Florian Weimer
@ 2011-01-18 22:16 ` Yannick Duchêne (Hibou57)
2011-01-19 6:58 ` Simon Wright
1 sibling, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 22:16 UTC (permalink / raw)
Le Tue, 18 Jan 2011 20:47:26 +0100, Adam Beneschan <adam@irvine.com> a
écrit:
> Maybe that's what the style guide author intended. If so, I think he
> had it completely backward. Look at the RM's descriptions of what the
> subprograms in language-defined packages do, and then try to figure
> out how to describe them without referring to parameter names. Try
> Ada.Strings.Unbounded.To_String and To_Unbounded_String, for example,
> in A.4.5(78-79). That's just the first thing I went to when I picked
> an Annex A section more or less arbitrarily---I didn't have to hunt
> for the "best example". Anyway, you *could* rewrite the description
> in a way that doesn't refer to the parameter names, but all you gain
> is verbosity and stilted-sounding language---at the expense of
> clarity, readability, and several dozen of your readers' brain cells.
This raise (one more time) the question of comment consistency with
source. We really need a standard convention to mark program identifiers
in comments (and corollary to precisely define scope of comments).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 20:23 ` Pascal Obry
2011-01-18 21:39 ` Georg Bauhaus
@ 2011-01-18 22:20 ` Yannick Duchêne (Hibou57)
1 sibling, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 22:20 UTC (permalink / raw)
Le Tue, 18 Jan 2011 21:23:36 +0100, Pascal Obry <pascal@obry.net> a écrit:
>
> Florian,
>
>> The problem is that the rule is self-contradictory. I think it should
>> say, "should not specifically mention", i.e., the opposite of what you
>> suggested.
>
> No, it is definitely "should specifically mention". We are talking about
> the formal name here. Please reread my response to Yannick about this
> one.
OK. Will forget about Florian's interpretation.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 22:01 ` Randy Brukardt
@ 2011-01-18 22:35 ` Yannick Duchêne (Hibou57)
2011-01-18 23:37 ` tmoran
1 sibling, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-18 22:35 UTC (permalink / raw)
Le Tue, 18 Jan 2011 23:01:29 +0100, Randy Brukardt <randy@rrsoftware.com>
a écrit:
> I'll second that. We created a pretty-printer for Janus/Ada years ago
> with
> the idea of using it to put all of our code into a common style. The
> results
> were not very pleasing and we never ended up using it. We still provide
> it
> to customers, but I don't think many are using it, as I've not had much
> luck
> using it. Once (not that long ago) I found that it made a complete mess
> out
> of task type declarations - it turned out they'd never been implemented
> at
> all. You'd think someone would report such things if they cared...
>
> Randy.
Development of a really pretty pretty-printer would requires long and
multiple refinement iterations. I us to have some thoughts in that area,
but never started up such a project (would be time consuming). However, if
anybody is dreaming about a pretty printer with long time support for
refinement and would be OK to fund it, please anyone, just tell me (just
drop me an e-mail).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
1 sibling, 1 reply; 96+ messages in thread
From: tmoran @ 2011-01-18 23:37 UTC (permalink / raw)
> I'll second that. We created a pretty-printer for Janus/Ada years ago with
> the idea of using it to put all of our code into a common style. The results
> were not very pleasing and we never ended up using it. We still provide it
> to customers, but I don't think many are using it, as I've not had much luck
> using it. Once (not that long ago) I found that it made a complete mess out
> of task type declarations - it turned out they'd never been implemented at
> all. You'd think someone would report such things if they cared...
I use it. It's less work to run it and then clean up the things I don't
like, than to try to do all the prettying, without missing anything, by
myself. It does handle task types - it's "protected" that it doesn't
understand, but changing that word to "package", then changing back,
is pretty simple. Sorry if I never reported the "protected" problem.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 22:13 ` Randy Brukardt
@ 2011-01-19 0:47 ` Georg Bauhaus
2011-01-19 1:06 ` Yannick Duchêne (Hibou57)
0 siblings, 1 reply; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-19 0:47 UTC (permalink / raw)
On 1/18/11 11:13 PM, Randy Brukardt wrote:
> "Georg Bauhaus"<rm.dash-bauhaus@futureapps.de> wrote in message
> news:4d3608ab$0$7664$9b4e6d93@newsspool1.arcor-online.net...
>> On 18.01.11 21:23, Pascal Obry wrote:
>>>
>>> Florian,
>>>
>>>> The problem is that the rule is self-contradictory. I think it should
>>>> say, "should not specifically mention", i.e., the opposite of what you
>>>> suggested.
>>>
>>> No, it is definitely "should specifically mention". We are talking about
>>> the formal name here. Please reread my response to Yannick about this
>>> one.
> [...] Indeed, I still have no idea what the second sentence of
> that style section is supposed to mean. I thought it meant the exact
> opposite of the first sentence (with which I agree wholeheartedly) -- the
> only way *not* to depend on the names is to not include them in the text.
> I'd probably suggest dropping it altogether -- I have no idea how to write a
> useful comment that doesn't depend on the names of things.
>
> Perhaps the point was that there always should be a comment (rather than
> expecting the name of the parameters to serve in place of a comment) -- in
> that case, the text needs to emphasize the need for comments rather than the
> reason for omitting them.
My guess was similar. When names will need to be changed,
the comments can otherwise stay intact:
procedure Call (Filename : String);
-- Filename must be an abosulute name
becomes
procedure Call (Path : String);
-- Path must be an abosulute name
(I am not suggesting that Path is better than Filename.)
However, when the name becomes "Frmbloo", as in
procedure Call (Frmbloo : String);
-- Frmbloo must be an abosulute name
the comment shows that it does depend on the names of things:
The "file" part has gone missing, leaving a blank that the reader
cannot fill in by inference from either the name or from the comment.
What is a Frmbloo?
The comment specifically mentions the formal argument name,
as should be. However, the comment does depend on the name of
things.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 10:04 ` Georg Bauhaus
0 siblings, 2 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 1:06 UTC (permalink / raw)
Le Wed, 19 Jan 2011 01:47:33 +0100, Georg Bauhaus
<rm-host.bauhaus@maps.futureapps.de> a écrit:
> My guess was similar. When names will need to be changed,
> the comments can otherwise stay intact:
>
> procedure Call (Filename : String);
> -- Filename must be an abosulute name
>
> becomes
>
> procedure Call (Path : String);
> -- Path must be an abosulute name
>
> (I am not suggesting that Path is better than Filename.)
> However, when the name becomes "Frmbloo", as in
>
> procedure Call (Frmbloo : String);
> -- Frmbloo must be an abosulute name
>
> the comment shows that it does depend on the names of things:
> The "file" part has gone missing, leaving a blank that the reader
> cannot fill in by inference from either the name or from the comment.
> What is a Frmbloo?
>
> The comment specifically mentions the formal argument name,
> as should be. However, the comment does depend on the name of
> things.
So this turn to be a suggestion about the good way to name program
elements ? If a name is natural enough, it appears similarly naturally in
comments and is less likely to be changed, so less likely to become a
matter about broken sync between comment and source.
By the way, to talk about these particular identifiers, the File_Name vs
Path is troublesome to me. From source to source in multiple places, the
definition of a file name seems to vary: sometime the file base name +
file extension, without directory, sometime the directory to which is
appended the file base name and extension. I feel this should always be
file base name + extension without directory, so that you may have
Directory_Name the same way there may be File_Name, and Entry_Name when
the type is unknown (either file or directory).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
0 siblings, 1 reply; 96+ messages in thread
From: Simon Wright @ 2011-01-19 6:58 UTC (permalink / raw)
"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:
> This raise (one more time) the question of comment consistency with
> source. We really need a standard convention to mark program
> identifiers in comments (and corollary to precisely define scope of
> comments).
-- @Path is the name of the file to be called.
procedure Call (Path : String);
would be the Javadoc way (just for parameters, there's be more to it, as
you say).
I haven't investigated whether gnathtml.pl or AdaBrowse or AdaDoc
support such a feature already. AdaBrowse and AdaDoc seem to have
stalled?
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
1 sibling, 1 reply; 96+ messages in thread
From: J-P. Rosen @ 2011-01-19 7:00 UTC (permalink / raw)
Le 19/01/2011 02:06, Yannick Duchêne (Hibou57) a écrit :
I feel this should always be
> file base name + extension without directory,
>
Plus version, plus whatever the OS adds to the name. Don't think every
OS uses the DOS/Unix base name + extension scheme.
(Granted: I'm a former VMS lover)
--
---------------------------------------------------------
J-P. Rosen (rosen@adalog.fr)
Adalog a déménagé / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
` (2 more replies)
2011-01-19 11:21 ` Stephen Leake
1 sibling, 3 replies; 96+ messages in thread
From: J-P. Rosen @ 2011-01-19 7:19 UTC (permalink / raw)
Le 18/01/2011 23:03, Yannick Duchêne (Hibou57) a écrit :
> Just wanted to underline again what Pascal Obry also said (and I fully
> agree with, and others too) : the line length limitation is not due to
> any inheritance from old and obsolete systems, this has ergonomic
> motivations. He pointed the example of news-paper. The typical width of
> a news paper or magazine text is even lower : 40 or 50 characters width
> is a common layout. If you doubt, then a question : where do you think
> these old systems get this default screen width of 80 characters ? You
> think they were not able to do it wider ? Answer : from the ergonomic
> principle stated above. 80 characters width was not due to technical
> limitations, this was a target specification.
>
I beg to (partially) disagree here: reading a newspaper has nothing to
do with reading a program. Columns are intended to have a width that
allows to grasp the whole line without having to move the eyeball - thus
increasing the speed of reading. This is possible because the average
word is 5 letters long, and that the brain is able to reconstruct a
sentence from partial information (fast reading is about not reading
word-by-word).
In programming, most identifiers are far longer than five characters,
especially if you are use-phobic (hint, hint). And you want to read
exactly what's written, not what your brain thinks is written!
The limitation to 80 characters has nothing to do with ergonomy, it was
the width of the 1928 IBM punched card (says one who programmed on
punched cards in his beginnings - not in 1928 though).
I agree that /some/limitation is necessary, but 80 is far to narrow,
leading to excessive folding in nested constructs. My personal taste is
for 120 columns - no problem to view that with any editor, even on small
screens.
--
---------------------------------------------------------
J-P. Rosen (rosen@adalog.fr)
Adalog a déménagé / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 7:00 ` J-P. Rosen
@ 2011-01-19 8:53 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 8:53 UTC (permalink / raw)
Le Wed, 19 Jan 2011 08:00:13 +0100, J-P. Rosen <rosen@adalog.fr> a écrit:
> Le 19/01/2011 02:06, Yannick Duchêne (Hibou57) a écrit :
> I feel this should always be
>> file base name + extension without directory,
>>
> Plus version, plus whatever the OS adds to the name. Don't think every
> OS uses the DOS/Unix base name + extension scheme.
>
> (Granted: I'm a former VMS lover)
True, I failed here. So whatever identifies a file in a directory.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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-19 9:13 ` Dmitry A. Kazakov
2011-01-19 18:02 ` Jeffrey Carter
2 siblings, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 9:07 UTC (permalink / raw)
Le Wed, 19 Jan 2011 08:19:39 +0100, J-P. Rosen <rosen@adalog.fr> a écrit:
> I beg to (partially) disagree here: reading a newspaper has nothing to
> do with reading a program. Columns are intended to have a width that
> allows to grasp the whole line without having to move the eyeball - thus
> increasing the speed of reading. This is possible because the average
> word is 5 letters long, and that the brain is able to reconstruct a
> sentence from partial information (fast reading is about not reading
> word-by-word).
>
> In programming, most identifiers are far longer than five characters,
> especially
I agree, that's what I also said in the last sentence of second paragraph.
By the way: that's not just with news-paper, the same apply to the web
(too much long line is a common criticism about bad page design).
> if you are use-phobic (hint, hint). And you want to read
> exactly what's written, not what your brain thinks is written!
Another topic. That's not really phobic, this is just that if one use
prefixed notation 95% of times, even those units which could be Used are
also used with prefix, for consistency.
> The limitation to 80 characters has nothing to do with ergonomy, it was
> the width of the 1928 IBM punched card (says one who programmed on
> punched cards in his beginnings - not in 1928 though).
I heard to say they agreed 80 characters was a good width. But you know
better than I (age matters here), so I may be wrong (I just share memories
written by some others, this may be error prone).
> I agree that /some/limitation is necessary, but 80 is far to narrow,
> leading to excessive folding in nested constructs. My personal taste is
> for 120 columns - no problem to view that with any editor, even on small
> screens.
Well, that's true 120 is nice too. However, it's already too large for
side by side view (as noticed by Pascal) even on a wide graphic screen,
and vertical tile is not nice (not enough height, you have to scroll all
the time and lose from view what you've just scrolled).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 7:19 ` J-P. Rosen
2011-01-19 9:07 ` Yannick Duchêne (Hibou57)
@ 2011-01-19 9:13 ` Dmitry A. Kazakov
2011-01-19 9:28 ` Yannick Duchêne (Hibou57)
2011-01-19 13:39 ` J-P. Rosen
2011-01-19 18:02 ` Jeffrey Carter
2 siblings, 2 replies; 96+ messages in thread
From: Dmitry A. Kazakov @ 2011-01-19 9:13 UTC (permalink / raw)
On Wed, 19 Jan 2011 08:19:39 +0100, J-P. Rosen wrote:
> I beg to (partially) disagree here: reading a newspaper has nothing to
> do with reading a program.
Of course it does, because the process of reading is same.
Program reading requires even shorter lines because the reader searches and
compares program texts more often than newspaper texts.
> In programming, most identifiers are far longer than five characters,
> especially if you are use-phobic (hint, hint).
Right, yet another argument for "use" against fully qualified names.
> And you want to read
> exactly what's written, not what your brain thinks is written!
Without brain thinking, you mean? (:-))
BTW, the argument to exactness works rather against you. Consider how texts
on mathematics are formatted. Formulae have always *shorter* lines than
plain texts, to be read "exactly."
> I agree that /some/limitation is necessary, but 80 is far to narrow,
> leading to excessive folding in nested constructs.
I disagree. The text should be possible to show side-by-side, e.g. ads and
adb files. Deeply nested constructs is IMO bad style, to be factored out
into local procedures.
--
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 6:58 ` Simon Wright
@ 2011-01-19 9:15 ` Yannick Duchêne (Hibou57)
2011-01-19 20:16 ` Simon Wright
` (2 more replies)
0 siblings, 3 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 9:15 UTC (permalink / raw)
Le Wed, 19 Jan 2011 07:58:52 +0100, Simon Wright <simon@pushface.org> a
écrit:
> would be the Javadoc way (just for parameters, there's be more to it, as
> you say).
>
> I haven't investigated whether gnathtml.pl or AdaBrowse or AdaDoc
> support such a feature already. AdaBrowse and AdaDoc seem to have
> stalled?
I don't know why you said “have stalled”, but I guess if these are based
on ASIS, as ASIS don't parse comments content, this may be a sufficient
reason (I forget which one, I am pretty sure one of AdaBrowse or AdaDoc at
least use ASIS).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 13:39 ` J-P. Rosen
1 sibling, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 9:28 UTC (permalink / raw)
Le Wed, 19 Jan 2011 10:13:34 +0100, Dmitry A. Kazakov
<mailbox@dmitry-kazakov.de> a écrit:
> On Wed, 19 Jan 2011 08:19:39 +0100, J-P. Rosen wrote:
>
>> I beg to (partially) disagree here: reading a newspaper has nothing to
>> do with reading a program.
>
> Of course it does, because the process of reading is same.
But the layout is not the same: you have longer “words” as you agreed
later, you have indent also.
>> In programming, most identifiers are far longer than five characters,
>> especially if you are use-phobic (hint, hint).
>
> Right, yet another argument for "use" against fully qualified names.
These phobic people who like qualified names, also like renaming
declarations to provide shorter prefix, you know ;)
> BTW, the argument to exactness works rather against you. Consider how
> texts
> on mathematics are formatted. Formulae have always *shorter* lines than
> plain texts, to be read "exactly."
Reformulated: you suggest the more you have to care to each single part,
to shorter the line should be.
Seems reasonable.
This could be confirmed by another common standard: one instruction per
line only (and I personally also try to do it “on expression per line
only” and use intermediate variable or constants for that purpose).
May be we should distinguish two kind of line length: the one which is
measured in characters, and the one which is measured in semes ? (seme =
semantic unit). The length in semes is more meaningful. What's the average
length in characters of a seme in a computer program source ? And what's
the average indent width ?
I feel we could agree we could go beyond 80 characters (seems OK). But 120
is too much. Well, let say 100 (cheese).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
0 siblings, 2 replies; 96+ messages in thread
From: Dmitry A. Kazakov @ 2011-01-19 10:04 UTC (permalink / raw)
On Wed, 19 Jan 2011 10:28:19 +0100, Yannick Duchêne (Hibou57) wrote:
> Le Wed, 19 Jan 2011 10:13:34 +0100, Dmitry A. Kazakov
> <mailbox@dmitry-kazakov.de> a écrit:
>
>> On Wed, 19 Jan 2011 08:19:39 +0100, J-P. Rosen wrote:
>>
>>> I beg to (partially) disagree here: reading a newspaper has nothing to
>>> do with reading a program.
>>
>> Of course it does, because the process of reading is same.
> But the layout is not the same: you have longer “words” as you agreed
> later, you have indent also.
That does not change the process of reading, which is a chemical reaction
in human body. The length of words may make this process slower or shorter,
less or more effective, but it cannot change the process.
>>> In programming, most identifiers are far longer than five characters,
>>> especially if you are use-phobic (hint, hint).
>>
>> Right, yet another argument for "use" against fully qualified names.
> These phobic people who like qualified names, also like renaming
> declarations to provide shorter prefix, you know ;)
I know, they have an impression that ATIO.Put_Line is more readable than
just Put_Line. Of course the same package must be renamed to different
names in different parts of the program in order to further "improve"
"readability." (:-))
>> BTW, the argument to exactness works rather against you. Consider how texts
>> on mathematics are formatted. Formulae have always *shorter* lines than
>> plain texts, to be read "exactly."
> Reformulated: you suggest the more you have to care to each single part,
> to shorter the line should be.
There is some optimal length, which could be directly derived from the
sight angle and the distance to the rendering surface. This is biologically
given.
> This could be confirmed by another common standard: one instruction per
> line only (and I personally also try to do it “on expression per line
> only” and use intermediate variable or constants for that purpose).
Yes, a good pick. Into the same basket: one variable declaration per line.
> May be we should distinguish two kind of line length: the one which is
> measured in characters, and the one which is measured in semes ? (seme =
> semantic unit). The length in semes is more meaningful.
There are differences in how chains of characters and chains of symbols are
recognized. Meaningful words are far easier to read. While reading known
words people actually read only prefixes and suffixes. The brain
automatically fills the gaps. Properly spelt words can be much longer than
arbitrary chains of symbols. BTW, this why graphical languages will never
make it, because written texts have the advantage of 10+ years of training
on perpetual daily reading, while arrows and blocks do not.
> What's the average
> length in characters of a seme in a computer program source ? And what's
> the average indent width ?
Indentation is a "semantic unit" in your classification.
> I feel we could agree we could go beyond 80 characters (seems OK). But 120
> is too much. Well, let say 100 (cheese).
I stick to my 72.
--
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 1:06 ` Yannick Duchêne (Hibou57)
2011-01-19 7:00 ` J-P. Rosen
@ 2011-01-19 10:04 ` Georg Bauhaus
2011-01-19 11:42 ` Yannick Duchêne (Hibou57)
1 sibling, 1 reply; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-19 10:04 UTC (permalink / raw)
On 1/19/11 2:06 AM, Yannick Duchêne (Hibou57) wrote:
> Le Wed, 19 Jan 2011 01:47:33 +0100, Georg Bauhaus <rm-host.bauhaus@maps.futureapps.de> a écrit:
>> The comment specifically mentions the formal argument name,
>> as should be. However, the comment does depend on the name of
>> things.
> So this turn to be a suggestion about the good way to name program elements ?
Following the particular AWS rule, the formal argument name
should be mentioned, but not otherwise matter much. IIUC. The
comment then can perhaps be written
procedure Call (Frmbloo : String);
-- @{Frmbloo@} is an absolute name of an executable file
-- to be called
(Regarding the comment markup, I first thought "{{Frmbloo}}";
however, mathematical sets, very useful in comments, can have
sets as elements, "{{" becomes ambigous". "{{" might be too
similar to "((", too, the latter being valid Ada source text.
The @{ @} construct, sufficiently unique yet simple, can bracket
inline Ada source of any kind; "@@" (or some another pair)
will---if needed---provide for line-wise switching
complementing "--" and eases the writing of coding examples in
comments. The comments can then be checked by compilers and
tools.
(If programmers didn't suffer from Unicode phobia, the language
designers could pick symbols for bracketing not otherwise used
such as right and left pointing triangles. Alas, digraphs rule...)
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 1:40 ` Bill Findlay
@ 2011-01-19 11:12 ` Stephen Leake
0 siblings, 0 replies; 96+ messages in thread
From: Stephen Leake @ 2011-01-19 11:12 UTC (permalink / raw)
Bill Findlay <news@findlayw.plus.com> writes:
> On 18/01/2011 00:45, in article
> a4cd6433-57ed-49ae-9d30-4f358c28caac@m20g2000prc.googlegroups.com, "Adam
> Beneschan" <adam@irvine.com> wrote:
>
>> On Jan 17, 5:47 am, Bill Findlay <n...@findlayw.plus.com> wrote:
>>
>>>>> 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).
>>>
>>> Why 78/79 and not 80, as I have always used?
>>
>> I tend to make all my windows 80 characters wide. I use EMACS, which
>> reserves the 80th character for a wrapping indicator, so that if you
>> used it on a source with an 80-character line, EMACS would display
>> only 79 of those on the first line, put a mark in the 80th character
>> indicating that the line is wrapped, and then display the 80th
>> character on the next line.
>
> Ah, EMACS: 1970s software that's as bad as 1970s terminal hardware!
Emacs (It's no longer an acronym) has been around that long, but unlike
the terminal hardware, it has undergone continual improvement. The
current release is far better than any other IDE I've tried.
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 9:11 ` pascal.obry
@ 2011-01-19 11:17 ` Stephen Leake
2011-01-19 11:53 ` Yannick Duchêne (Hibou57)
0 siblings, 1 reply; 96+ messages in thread
From: Stephen Leake @ 2011-01-19 11:17 UTC (permalink / raw)
"pascal.obry@gmail.com" <pascal.obry@gmail.com> writes:
> On Jan 18, 9:04 am, Stephen Leake <stephen_le...@stephe-leake.org>
> wrote:
>> I use 120 character text areas; much more readable with reasonable name
>> lengths.
>
> But hard to read a diff
Why?
> and almost impossible to have a side by side view to resolve merge
> conflicts (with meld, diffuse...)
No problem on a 24" 1920 x 1024 display.
> Newspaper have short lines to help read fast. Longer the line is,
> harder it
> is to go back to the next line.
Yes, but there is also such a thing as "too short". The optimum length
depends on the length of the individual words, and on the typical amount
of indentation.
Reading natural language prose is _not_ the same process as reading Ada
code.
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 22:03 ` Yannick Duchêne (Hibou57)
2011-01-19 7:19 ` J-P. Rosen
@ 2011-01-19 11:21 ` Stephen Leake
2011-01-19 13:32 ` Yannick Duchêne (Hibou57)
1 sibling, 1 reply; 96+ messages in thread
From: Stephen Leake @ 2011-01-19 11:21 UTC (permalink / raw)
"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:
> If you doubt, then a question : where do
> you think these old systems get this default screen width of 80
> characters ? You think they were not able to do it wider ? Answer :
> from the ergonomic principle stated above. 80 characters width was
> not due to technical limitations, this was a target specification.
And it was appropriate for the languages of the time; assembler,
FORTRAN.
Languages have improved, it's time to reevaluate that ergonomic
conclusion.
Do you have any evidence that 80 is still the right number?
I have personal experience that 120 is better for me.
> If there is an area where we still unfortunately stick to old obsolete
> systems, the is not about text width, this about two other points: 1)
> ASCII heritage vs Unicode (using either Emacs or VIM for
> multi-language text files is simply *impossible* most of the time,
This has gotten much better in Emacs recently; it fully supports UTF-8.
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 10:04 ` Georg Bauhaus
@ 2011-01-19 11:42 ` Yannick Duchêne (Hibou57)
2011-01-19 13:17 ` Georg Bauhaus
0 siblings, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 11:42 UTC (permalink / raw)
Le Wed, 19 Jan 2011 11:04:55 +0100, Georg Bauhaus
<rm-host.bauhaus@maps.futureapps.de> a écrit:
> (Regarding the comment markup, I first thought "{{Frmbloo}}";
> however, mathematical sets, very useful in comments, can have
> sets as elements, "{{" becomes ambigous". "{{" might be too
> similar to "((", too, the latter being valid Ada source text.
> The @{ @} construct, sufficiently unique yet simple, can bracket
> inline Ada source of any kind; "@@" (or some another pair)
> will---if needed---provide for line-wise switching
> complementing "--" and eases the writing of coding examples in
> comments. The comments can then be checked by compilers and
> tools.
Looks good. The use of “@” is also quite common in one well known LP
notations : FunnelWeb. So this is a somewhat already existing standard.
After all, LP writes program text inside of natural text… and this is
exactly what this is about with comments.
According to the authoritative FunnelWeb documentation, which you can
access here:
http://www.ross.net/funnelweb/tutorial/intro_hello.html
the body of a macros, whose purpose is to expand into program text, is
exactly the same as the one you suggested! This would be a clever re-use
of one of the most famous LP notation. By the way, this guy, Ross
Williams, the author of FunnelWeb, was also a fan of Ada… see how this
story is funny ? ;)
> (If programmers didn't suffer from Unicode phobia, the language
> designers could pick symbols for bracketing not otherwise used
> such as right and left pointing triangles. Alas, digraphs rule...)
The font too should not suffer from Unicode phobia. Mono-spaced fonts are
oftenly poor at supporting Unicode (lack of too many character range). I
would suggest “DejaVu Sans Mono” here (good support, the one I use, so I
can tell).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 11:17 ` Stephen Leake
@ 2011-01-19 11:53 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 11:53 UTC (permalink / raw)
Le Wed, 19 Jan 2011 12:17:34 +0100, Stephen Leake
<stephen_leake@stephe-leake.org> a écrit:
>> and almost impossible to have a side by side view to resolve merge
>> conflicts (with meld, diffuse...)
>
> No problem on a 24" 1920 x 1024 display.
Mine which I feel is big, is “only” 1440 x 900, so less. Many laptops are
less too. And there is an increase limit: the smaller the pixel is, the
more you are likely to need increase font size. Higher screen definition
does not imply larger text width. Even printed book have a limit, although
its printed paper (which is very high definition).
>> Newspaper have short lines to help read fast. Longer the line is,
>> harder it
>> is to go back to the next line.
>
> Yes, but there is also such a thing as "too short". The optimum length
> depends on the length of the individual words, and on the typical amount
> of indentation.
>
> Reading natural language prose is _not_ the same process as reading Ada
> code.
Agree too.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
1 sibling, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 12:16 UTC (permalink / raw)
Le Wed, 19 Jan 2011 11:04:42 +0100, Dmitry A. Kazakov
<mailbox@dmitry-kazakov.de> a écrit:
> There are differences in how chains of characters and chains of symbols
> are
> recognized. Meaningful words are far easier to read. While reading known
> words people actually read only prefixes and suffixes. The brain
> automatically fills the gaps. Properly spelt words can be much longer
> than
> arbitrary chains of symbols. BTW, this why graphical languages will never
> make it, because written texts have the advantage of 10+ years of
> training
> on perpetual daily reading, while arrows and blocks do not.
Valuable notice. This may be confirmed: I know some ones expressed the
need (and at least some have even implemented) for a text based version of
UML (not ASCII art, literate UML). However, as already noticed in an older
thread at CLA, diagrams has the strength or being two dimensional, and
that help to embrace complexity. In this same thread, some one gave a link
to a study which demonstrated that SPARK + graphical notation to express
system design was the success keys for safety critical applications. Box
and arrows seems better at outlining than text is (although outline with
text is possible). We have a french expression which literally says « une
image parle mieux qu’un long discours », which could be translated as “a
picture tells more than a long speech”. This is true for some matters But
to express the details requires text, and concrete implementation is
required to express all details without a single lack.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
` (2 more replies)
0 siblings, 3 replies; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-19 13:17 UTC (permalink / raw)
On 19.01.11 12:42, Yannick Duchêne (Hibou57) wrote:
> According to the authoritative FunnelWeb documentation, which you can access
> here:
> http://www.ross.net/funnelweb/tutorial/intro_hello.html
> the body of a macros, whose purpose is to expand into program text, is exactly
> the same as the one you suggested!
No, no, the brackets @{ @}, or the line-of-code indicator @@ are much
simpler than FunnelWeb. For one thing, the Ada programmer only needs
to understand Ada and will not think about typesetting or macros or
line endings.
> The font too should not suffer from Unicode phobia. Mono-spaced fonts are
> oftenly poor at supporting Unicode (lack of too many character range). I would
> suggest “DejaVu Sans Mono” here (good support, the one I use, so I can tell).
(AFAICT, Lucida and Hershey fixed width fonts were created
specifically for Unicode, at the time; Plan 9 is a Unicode
operating system and has always had comprehensive Unicode fonts.
I believe this has been true of Windows(TM) as well.
Maybe the regional font makers, the Latin-X delusions, and
the stereotypical dexterity with ASCII keyboards (where
1 keystroke is supposed to produce 1 letter) have been
in the way.)
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 9:07 ` Yannick Duchêne (Hibou57)
@ 2011-01-19 13:31 ` J-P. Rosen
2011-01-20 1:53 ` Stephen Leake
0 siblings, 1 reply; 96+ messages in thread
From: J-P. Rosen @ 2011-01-19 13:31 UTC (permalink / raw)
Le 19/01/2011 10:07, Yannick Duchêne (Hibou57) a écrit :
> Well, that's true 120 is nice too. However, it's already too large for
> side by side view (as noticed by Pascal) even on a wide graphic screen,
> and vertical tile is not nice (not enough height, you have to scroll all
> the time and lose from view what you've just scrolled).
>
I don't think it is a strong argument (speaking for myself):
1) I use diff very rarely
2) If I do, I use WinMerge (on Windows) or Meld (on Linux), both handle
long lines nicely (scrolling both lines horizontally in sync).
--
---------------------------------------------------------
J-P. Rosen (rosen@adalog.fr)
Adalog a déménagé / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 11:21 ` Stephen Leake
@ 2011-01-19 13:32 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 13:32 UTC (permalink / raw)
Le Wed, 19 Jan 2011 12:21:29 +0100, Stephen Leake
<stephen_leake@stephe-leake.org> a écrit:
>> If there is an area where we still unfortunately stick to old obsolete
>> systems, the is not about text width, this about two other points: 1)
>> ASCII heritage vs Unicode (using either Emacs or VIM for
>> multi-language text files is simply *impossible* most of the time,
>
> This has gotten much better in Emacs recently; it fully supports UTF-8.
Confirmed (just tested): for Windows users, don't get it from the stable
release (tested, just half success), get it from the alpha release (test,
full success). This is named Emacs 24. You may just have to read the doc
about Bidi if you need.
http://alpha.gnu.org/gnu/emacs/windows/
(don't get a *-barebin-*, it does not contain all the required stuff to
run, get a *-bin-* instead)
The last was just updated this month, and is OK.
Now let's test this famous ada-mode :) (at least just to know what it
looks like)
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 9:13 ` Dmitry A. Kazakov
2011-01-19 9:28 ` Yannick Duchêne (Hibou57)
@ 2011-01-19 13:39 ` J-P. Rosen
2011-01-19 14:20 ` Dmitry A. Kazakov
2011-01-19 21:47 ` Yannick Duchêne (Hibou57)
1 sibling, 2 replies; 96+ messages in thread
From: J-P. Rosen @ 2011-01-19 13:39 UTC (permalink / raw)
Le 19/01/2011 10:13, Dmitry A. Kazakov a �crit :
>> And you want to read
>> exactly what's written, not what your brain thinks is written!
>
> Without brain thinking, you mean? (:-))
>
I noticed the smiley, but kidding apart, I think it is very important to
realize that you don't read what is written, but what you think is
written. How many times do you chase bugs that eventually resolved to
modifying the wrong variable, and you read that damn assignment ten
times before realizing it was the wrong variable ?!
> BTW, the argument to exactness works rather against you. Consider how texts
> on mathematics are formatted. Formulae have always *shorter* lines than
> plain texts, to be read "exactly."
Hmmm... when you start having names that do not fit on one line, you
really have a readability problem.
>
>> I agree that /some/limitation is necessary, but 80 is far to narrow,
>> leading to excessive folding in nested constructs.
>
> I disagree. The text should be possible to show side-by-side, e.g. ads and
> adb files.
I don't see why (see my other post)
> Deeply nested constructs is IMO bad style, to be factored out
> into local procedures.
>
Of course, but if you consider named notation in subprogram calls (good
programming practice certainly), where you want all arrows aligned (good
presentation too), and a parameter is itself a function call, and you
have some explicit long names, you end up quite easily close to the
right margin.
--
---------------------------------------------------------
J-P. Rosen (rosen@adalog.fr)
Adalog a d�m�nag� / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 21:47 ` Yannick Duchêne (Hibou57)
1 sibling, 1 reply; 96+ messages in thread
From: Dmitry A. Kazakov @ 2011-01-19 14:20 UTC (permalink / raw)
On Wed, 19 Jan 2011 14:39:11 +0100, J-P. Rosen wrote:
> Le 19/01/2011 10:13, Dmitry A. Kazakov a �crit :
>>> And you want to read
>>> exactly what's written, not what your brain thinks is written!
>>
>> Without brain thinking, you mean? (:-))
>>
> I noticed the smiley, but kidding apart, I think it is very important to
> realize that you don't read what is written, but what you think is
> written.
Right, and it is always so. Perception is a part of the process of
thinking.
> How many times do you chase bugs that eventually resolved to
> modifying the wrong variable, and you read that damn assignment ten
> times before realizing it was the wrong variable ?!
Yes, because there is a mental model of the program is in the programmer's
head. The correspondence of this model to the reality expressed in the
language is never exact. Thinking and reading is necessary in order to
improve the correspondence.
I think that you meant a different thing: how well defined is the semantics
of the language being read. The semantics of the newspaper language is very
ill-defined, Ada is much better. But this is in no direct relation to
understanding of written texts in the above sense. Diffuse and
self-contradictory semantics can be easier to capture than the precise and
correct one, and conversely. Further, there is no obvious reason why the
process of reading should be different in both cases. I would say that it
is pretty same and that the quality of text is a thing quite unrelated to
its contents.
>> BTW, the argument to exactness works rather against you. Consider how texts
>> on mathematics are formatted. Formulae have always *shorter* lines than
>> plain texts, to be read "exactly."
> Hmmm... when you start having names that do not fit on one line, you
> really have a readability problem.
Sure, but we read different consequences from this. You believe that making
lines a bit longer would solve the problem. I do not.
>> Deeply nested constructs is IMO bad style, to be factored out
>> into local procedures.
>>
> Of course, but if you consider named notation in subprogram calls (good
> programming practice certainly), where you want all arrows aligned (good
> presentation too), and a parameter is itself a function call, and you
> have some explicit long names, you end up quite easily close to the
> right margin.
Not really. In fact, keyed notation is horizontally shorter because:
Draw_Value (Widget, 12.8 * Get_Current_Factor (Panel), ...);
is replaced with
Draw_Value
( Widget => Widget,
Value => 12.8 * Get_Current_Factor (Panel),
...
);
--
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
0 siblings, 2 replies; 96+ messages in thread
From: J-P. Rosen @ 2011-01-19 14:52 UTC (permalink / raw)
Le 19/01/2011 15:20, Dmitry A. Kazakov a �crit :
> I think that you meant a different thing: how well defined is the semantics
> of the language being read. The semantics of the newspaper language is very
> ill-defined, Ada is much better. But this is in no direct relation to
> understanding of written texts in the above sense. Diffuse and
> self-contradictory semantics can be easier to capture than the precise and
> correct one, and conversely. Further, there is no obvious reason why the
> process of reading should be different in both cases. I would say that it
> is pretty same and that the quality of text is a thing quite unrelated to
> its contents.
What I meant is that the sentences in journal are quite predictable, and
if you miss some information, you can trust that the brain will
reconstruct it correctly. Moreover, it is optimized for speed of reading.
Reading a program should be optimized for accuracy of understanding, and
making sure that no misinterpretation can happen. I claim these are
different goals.
--
---------------------------------------------------------
J-P. Rosen (rosen@adalog.fr)
Adalog a d�m�nag� / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
1 sibling, 0 replies; 96+ messages in thread
From: Dmitry A. Kazakov @ 2011-01-19 15:25 UTC (permalink / raw)
On Wed, 19 Jan 2011 15:52:14 +0100, J-P. Rosen wrote:
> Le 19/01/2011 15:20, Dmitry A. Kazakov a �crit :
>> I think that you meant a different thing: how well defined is the semantics
>> of the language being read. The semantics of the newspaper language is very
>> ill-defined, Ada is much better. But this is in no direct relation to
>> understanding of written texts in the above sense. Diffuse and
>> self-contradictory semantics can be easier to capture than the precise and
>> correct one, and conversely. Further, there is no obvious reason why the
>> process of reading should be different in both cases. I would say that it
>> is pretty same and that the quality of text is a thing quite unrelated to
>> its contents.
> What I meant is that the sentences in journal are quite predictable, and
> if you miss some information, you can trust that the brain will
> reconstruct it correctly. Moreover, it is optimized for speed of reading.
>
> Reading a program should be optimized for accuracy of understanding, and
> making sure that no misinterpretation can happen. I claim these are
> different goals.
Why? In both cases the text is to convey something to be reconstructed in
the most easy and quick way. Whether it be a picture of a flood or
earthquake happened somewhere or a variable assigned to a certain value is
no matter.
("Accuracy of understanding" depends on the contents. I would not say that
"flood in X, Y missing, Z homeless" is less or more accurate than "X := 1;"
Both are abstractions on some physical world events, which could be
infinitely more precise than their descriptions.)
--
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 7:19 ` J-P. Rosen
2011-01-19 9:07 ` Yannick Duchêne (Hibou57)
2011-01-19 9:13 ` Dmitry A. Kazakov
@ 2011-01-19 18:02 ` Jeffrey Carter
2 siblings, 0 replies; 96+ messages in thread
From: Jeffrey Carter @ 2011-01-19 18:02 UTC (permalink / raw)
On 01/19/2011 12:19 AM, J-P. Rosen wrote:
>
> I agree that /some/limitation is necessary, but 80 is far to narrow,
> leading to excessive folding in nested constructs. My personal taste is
> for 120 columns - no problem to view that with any editor, even on small
> screens.
For about 25 years, I have used as many characters as could be printed in
landscape on a sheet of paper with a readable, mono-space font: 130. I have
never had any problem with this limit.
--
Jeff Carter
"You me on the head hitted."
Never Give a Sucker an Even Break
108
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
2 siblings, 1 reply; 96+ messages in thread
From: Simon Wright @ 2011-01-19 20:16 UTC (permalink / raw)
"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:
> Le Wed, 19 Jan 2011 07:58:52 +0100, Simon Wright <simon@pushface.org>
> a écrit:
>> would be the Javadoc way (just for parameters, there's be more to it, as
>> you say).
>>
>> I haven't investigated whether gnathtml.pl or AdaBrowse or AdaDoc
>> support such a feature already. AdaBrowse and AdaDoc seem to have
>> stalled?
> I don't know why you said “have stalled”, but I guess if these are
> based on ASIS, as ASIS don't parse comments content, this may be a
> sufficient reason (I forget which one, I am pretty sure one of
> AdaBrowse or AdaDoc at least use ASIS).
By "have stalled" I meant "haven't been updated for quite a while". Of
course, quite a lot of my projects might look the same...
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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
1 sibling, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 21:43 UTC (permalink / raw)
Le Wed, 19 Jan 2011 15:52:14 +0100, J-P. Rosen <rosen@adalog.fr> a écrit:
> What I meant is that the sentences in journal are quite predictable, and
> if you miss some information, you can trust that the brain will
> reconstruct it correctly. Moreover, it is optimized for speed of reading.
>
> Reading a program should be optimized for accuracy of understanding, and
> making sure that no misinterpretation can happen. I claim these are
> different goals.
To confirm this, and also in reply to Dmitry. There are at least two
differences in formal language vs natural language.
Dmitry,
The natural language is known to be redundant and these redundancies vary.
Ex, you have in french, a tiny word meaning the plural, “les”, and when it
is associated to a word, this peer also get another mark, meaning the
plural too, “s” (to keep it simple). If ever a word got the “s” while it
is not associated to “les”, or is associated to “les” while it does not
hold the “s”, you may say, “ouch, there must be an error here”. If the
latter occurs, how could you say if the word is plural or not ? You may
think natural language dos not help a lot here and semantic of Ada is far
above… humm, not sure: at least the natural language gave you an
opportunity to feel there is an error. This is to what the redundancy
about the plural is often useful to (and many other strange things behave
the same way). The reader or the audience may also be able to correct
using some other inference to guess what the status of the word was
intended to be.
The second example is about to be implicit. There is a more or less
constant context in natural language, which is a consequence of a more or
less constant environment I suppose (our expression in our language is in
reference to our environment, for some numerous parts). This implicit
helps to feel possible holes the speech/text may contains. Well, this is
not real a formal way of doing things, and to help, many checks (among
ones the one exposed above) are involved.
With a language like Ada (or Lisp, or Python or whatever), while very
nice, none of the above applies: an error is an error and there is nothing
which gonna make it somewhat obvious to your eyes. Of course, there are
spelling mistakes in identifiers, but a statically checked language like
Ada already do this job for you at compile time. The error you have to
deal with are more pernicious and deals with consequences (this is not the
same kind of interpretation as a natural language which is more
declarative… but I do not mean it is declarative the same way declarative
programing languages are).
In short: not self-check opportunity, no implicit and different kind of
consequences in the end.
Reading Ada source and reading a news-paper is indeed like comparing
Halley's Comet and the Earth.
Now, what checks did you applied while reading me ? What implicit truths
did you had in mind for you inferences and understanding ? And above all,
how did you interpreted this in the whole ? You see ? ;) Would be funny to
see, but we may even never ever see. If you did not interpreted this the
way I wanted to mean it, you will not crash, I will not crash, and we will
probably recover (may not be consciously), re-sync in many ways, and many
other funny behaviors. That's just a third example of the difference
between this kind of natural language and formal languages.
Just see how natural language text are laid out: not the same at all, its
mainly flow like (and in the area of text layout, we indeed talk about
“flow”). This layout difference is the expression of different needs and
requirements to read.
(hope this was meaningful enough)
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 13:39 ` J-P. Rosen
2011-01-19 14:20 ` Dmitry A. Kazakov
@ 2011-01-19 21:47 ` Yannick Duchêne (Hibou57)
2011-01-21 19:17 ` Robert Matthews
1 sibling, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 21:47 UTC (permalink / raw)
Le Wed, 19 Jan 2011 14:39:11 +0100, J-P. Rosen <rosen@adalog.fr> a écrit:
>> Without brain thinking, you mean? (:-))
>>
> I noticed the smiley, but kidding apart, I think it is very important to
> realize that you don't read what is written, but what you think is
> written. How many times do you chase bugs that eventually resolved to
> modifying the wrong variable, and you read that damn assignment ten
> times before realizing it was the wrong variable ?!
That's precisely why source-review is better made by some-one else than by
your-self. Fortunately, if you really need to do it your self (if you are
single in a project), you still have an option: wait for some time, some
weeks or preferably some months (without coming back to that source), to
review your self (you will read it with different eyes).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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 19:59 ` Yannick Duchêne (Hibou57)
2 siblings, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-19 21:56 UTC (permalink / raw)
Le Wed, 19 Jan 2011 14:17:56 +0100, Georg Bauhaus
<rm.dash-bauhaus@futureapps.de> a écrit:
> No, no, the brackets @{ @}, or the line-of-code indicator @@ are much
> simpler than FunnelWeb. For one thing, the Ada programmer only needs
> to understand Ada and will not think about typesetting or macros or
> line endings.
Where you said “typesetting”, did you meant “semantic markup” ?
Also, I did not really understood the last sentence. He/she did not,
because he/she should not or he/she don't while he/she should ?
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 21:43 ` Yannick Duchêne (Hibou57)
@ 2011-01-19 22:20 ` Dmitry A. Kazakov
0 siblings, 0 replies; 96+ messages in thread
From: Dmitry A. Kazakov @ 2011-01-19 22:20 UTC (permalink / raw)
On Wed, 19 Jan 2011 22:43:33 +0100, Yannick Duch�ne (Hibou57) wrote:
> The natural language is known to be redundant and these redundancies vary.
Yes. So are most of artificial languages too. To put it simple: a random
sequence of ASCII characters is not a legal program. A random sequence of
phonemes is not a speech.
> The second example is about to be implicit. There is a more or less
> constant context in natural language,
Right, and artificial languages are no different either. You always have a
context, scope, state you implicitly refer to. There is just no other way
to have it. The context = the internal state of the reader, be it you, me
Ada compiler or Martians.
> With a language like Ada (or Lisp, or Python or whatever), while very
> nice, none of the above applies: an error is an error and there is nothing
> which gonna make it somewhat obvious to your eyes.
You are confusing here sematic errors and language errors [syntax, grammar
etc].
"The gostak distims the doshes"
"Colorless green ideas sleep furiously"
are famous examples of syntactically correct meaningless sentences. Is here
something helping you to do something with them?
declare
type Four is range 1..4:
X : Four := 45.7; -- You well know what is wrong here
begin
...
> Now, what checks did you applied while reading me ? What implicit truths
> did you had in mind for you inferences and understanding ? And above all,
> how did you interpreted this in the whole ? You see ? ;) Would be funny to
> see, but we may even never ever see. If you did not interpreted this the
> way I wanted to mean it, you will not crash, I will not crash, and we will
> probably recover (may not be consciously), re-sync in many ways, and many
> other funny behaviors. That's just a third example of the difference
> between this kind of natural language and formal languages.
This is a false analogy. Human brain is not a program, it is a processor.
Nothing wrong happens with your computer if you feed it with an illegal Ada
program. It is accepted or rejected in some way. So does the human brain,
you have a choice to accept (understand, agree) or not, maybe mistakenly or
rightfully. No difference whatsoever.
--
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 9:15 ` Yannick Duchêne (Hibou57)
2011-01-19 20:16 ` Simon Wright
@ 2011-01-19 22:21 ` Florian Weimer
2011-01-20 1:52 ` Stephen Leake
2 siblings, 0 replies; 96+ messages in thread
From: Florian Weimer @ 2011-01-19 22:21 UTC (permalink / raw)
* Yannick Duchêne (Hibou57):
> I don't know why you said “have stalled”, but I guess if these are
> based on ASIS, as ASIS don't parse comments content, this may be a
> sufficient reason (I forget which one, I am pretty sure one of
> AdaBrowse or AdaDoc at least use ASIS).
ASIS has access to comments, or it did ten years ago. (Back then, I
toyed with a Javadoc-style tool once, too.)
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 20:16 ` Simon Wright
@ 2011-01-19 22:42 ` Peter C. Chapin
0 siblings, 0 replies; 96+ messages in thread
From: Peter C. Chapin @ 2011-01-19 22:42 UTC (permalink / raw)
On 2011-01-19 15:16, Simon Wright wrote:
>> I don't know why you said “have stalled”, but I guess if these are
>> based on ASIS, as ASIS don't parse comments content, this may be a
>> sufficient reason (I forget which one, I am pretty sure one of
>> AdaBrowse or AdaDoc at least use ASIS).
AdaDoc does not use ASIS. It has it's own Ada95 parser.
Peter
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 21:56 ` Yannick Duchêne (Hibou57)
@ 2011-01-19 23:34 ` Georg Bauhaus
0 siblings, 0 replies; 96+ messages in thread
From: Georg Bauhaus @ 2011-01-19 23:34 UTC (permalink / raw)
On 1/19/11 10:56 PM, Yannick Duchêne (Hibou57) wrote:
> Le Wed, 19 Jan 2011 14:17:56 +0100, Georg Bauhaus <rm.dash-bauhaus@futureapps.de> a écrit:
>> No, no, the brackets @{ @}, or the line-of-code indicator @@ are much
>> simpler than FunnelWeb. For one thing, the Ada programmer only needs
>> to understand Ada and will not think about typesetting or macros or
>> line endings.
> Where you said “typesetting”, did you meant “semantic markup” ?
(I meant typesetting. A few bits of FunnelWeb are made for
typesetting. I wouldn't want to drag these in.)
The very simple addition of @{ and @} to Ada comments would not
have semantic implications. It is only about making references
to Ada text explicit. Consider:
procedure P (ARG : in out TYP);
-- bla bla @{ARG@} bla bla
Assume further one rule which states whether comments are written
before or after associated Ada program text.
First, the current situation is not very different.
Ada programmers cannot explicitly indicate identifiers
in comments, due to lack of syntax. But they can and do
mention the function of a word. Stated explicitly, it
would read:
procedure P (ARG : in out TYP);
-- bla bla denoted by formal argument name ARG should bla bla
It is customary to abbreviate this phrase: A convention of contemporary
English makes us assume that a capital letter at the start of a word
(or an underscore within it), occurring in the middle of a sentence,
would imply an Ada item and not the word of spoken language.
Alas, this implicitness doesn't work for ARG in this particular example,
since the program text uses a convention of all caps for identifiers.
The Ada Rapporteur Group meaning is another plausible interpretation,
possibly creating further confusion in the reader's head.
The convention doesn't work in some other spoken languages.
It doesn't work for some words of English.
The syntactical bracketing, @{ARG@}, leaves no doubt as to
which entity the comment is about.
> Also, I did not really understood the last sentence. He/she did not, because he/she should not or he/she don't while he/she should ?
A programmer who writes @{Frmbloo@} will think that he/she
is making the word Frmbloo stand for the identifier and for nothing
else. Hence, there is no need to think about anything but Ada.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 9:15 ` Yannick Duchêne (Hibou57)
2011-01-19 20:16 ` Simon Wright
2011-01-19 22:21 ` Florian Weimer
@ 2011-01-20 1:52 ` Stephen Leake
2 siblings, 0 replies; 96+ messages in thread
From: Stephen Leake @ 2011-01-20 1:52 UTC (permalink / raw)
"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:
> Le Wed, 19 Jan 2011 07:58:52 +0100, Simon Wright <simon@pushface.org>
> a écrit:
>> would be the Javadoc way (just for parameters, there's be more to it, as
>> you say).
>>
>> I haven't investigated whether gnathtml.pl or AdaBrowse or AdaDoc
>> support such a feature already. AdaBrowse and AdaDoc seem to have
>> stalled?
> I don't know why you said “have stalled”, but I guess if these are
> based on ASIS, as ASIS don't parse comments content, this may be a
> sufficient reason
It's easy enough to add a comment parser on top of ASIS; ASIS does give
access to the comment text.
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 13:31 ` J-P. Rosen
@ 2011-01-20 1:53 ` Stephen Leake
0 siblings, 0 replies; 96+ messages in thread
From: Stephen Leake @ 2011-01-20 1:53 UTC (permalink / raw)
"J-P. Rosen" <rosen@adalog.fr> writes:
> Le 19/01/2011 10:07, Yannick Duchêne (Hibou57) a écrit :
>> Well, that's true 120 is nice too. However, it's already too large for
>> side by side view (as noticed by Pascal) even on a wide graphic screen,
>> and vertical tile is not nice (not enough height, you have to scroll all
>> the time and lose from view what you've just scrolled).
>>
> I don't think it is a strong argument (speaking for myself):
> 1) I use diff very rarely
> 2) If I do, I use WinMerge (on Windows) or Meld (on Linux), both handle
> long lines nicely (scrolling both lines horizontally in sync).
I prefer Emacs ediff, which (by default) displays the two files above
each other. You can configure it to display them side by side, but I
just like the default better.
--
-- Stephe
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-18 23:37 ` tmoran
@ 2011-01-20 2:14 ` Randy Brukardt
0 siblings, 0 replies; 96+ messages in thread
From: Randy Brukardt @ 2011-01-20 2:14 UTC (permalink / raw)
<tmoran@acm.org> wrote in message news:ih588j$665$1@speranza.aioe.org...
>> I'll second that. We created a pretty-printer for Janus/Ada years ago
>> with
>> the idea of using it to put all of our code into a common style. The
>> results
>> were not very pleasing and we never ended up using it. We still provide
>> it
>> to customers, but I don't think many are using it, as I've not had much
>> luck
>> using it. Once (not that long ago) I found that it made a complete mess
>> out
>> of task type declarations - it turned out they'd never been implemented
>> at
>> all. You'd think someone would report such things if they cared...
>
> I use it. It's less work to run it and then clean up the things I don't
> like, than to try to do all the prettying, without missing anything, by
> myself. It does handle task types - it's "protected" that it doesn't
> understand, but changing that word to "package", then changing back,
> is pretty simple. Sorry if I never reported the "protected" problem.
It's possible that you did report it rather than me stumbling on it when
updating the syntax.
Anyway, I'm pretty sure I fixed that in the beta version that you recently
received, so I don't think you have to do that anymore (if you do, I need to
know). I think I did that at the same time I did a half-hearted attempt at
implementing the Ada 2005 syntax in it (I say half-hearted because the
testing was pretty minimal; I think it works adequately but I didn't try
that many test cases).
Randy.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 5:18 ` Yannick Duchêne (Hibou57)
@ 2011-01-21 4:06 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-21 4:06 UTC (permalink / raw)
Le Mon, 17 Jan 2011 06:18:35 +0100, Yannick Duchêne (Hibou57)
<yannick_duchene@yahoo.fr> a écrit:
> Le Mon, 17 Jan 2011 06:07:58 +0100, Yannick Duchêne (Hibou57)
> <yannick_duchene@yahoo.fr> a écrit:
>> 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.
>
> Hem, finally no: not good if one want to preserve provision for any kind
> of grammatical checker (or any other applications dealing with natural
> language in sources). Any way, still thanks, because you helped me to
> make a decision ;)
This may have a title semantic after some thoughts (at least in french,
you do not end a title with a period, so omitting this period is not a
grammatical error, that's required). If so, this should have an empty line
before and an empty line after.
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
0 siblings, 1 reply; 96+ messages in thread
From: Robert Matthews @ 2011-01-21 19:17 UTC (permalink / raw)
Yannick Duchêne (Hibou57) wrote:
>
> That's precisely why source-review is better made by some-one else than by
> your-self. Fortunately, if you really need to do it your self (if you are
> single in a project), you still have an option: wait for some time, some
> weeks or preferably some months (without coming back to that source), to
> review your self (you will read it with different eyes).
I find a next-day review very effective.
Bob Matthews
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-21 19:17 ` Robert Matthews
@ 2011-01-21 19:54 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-21 19:54 UTC (permalink / raw)
Le Fri, 21 Jan 2011 20:17:07 +0100, Robert Matthews
<ignore@ramatthews.free-online.co.uk> a écrit:
> Yannick Duchêne (Hibou57) wrote:
>
>>
>> That's precisely why source-review is better made by some-one else than
>> by
>> your-self. Fortunately, if you really need to do it your self (if you
>> are
>> single in a project), you still have an option: wait for some time, some
>> weeks or preferably some months (without coming back to that source), to
>> review your self (you will read it with different eyes).
>
> I find a next-day review very effective.
>
> Bob Matthews
At least, after some minimal distance (or else one will always read it the
same, so always see the same, and always be blind to the same).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
1 sibling, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-24 5:13 UTC (permalink / raw)
Le Wed, 19 Jan 2011 11:04:42 +0100, Dmitry A. Kazakov
<mailbox@dmitry-kazakov.de> a écrit:
>> I feel we could agree we could go beyond 80 characters (seems OK). But
>> 120
>> is too much. Well, let say 100 (cheese).
>
> I stick to my 72.
According to the french version of the comp.lang.ada's FAQ, postings to
the Usenet should be laid out using 72 characters wide lines:
http://fr.wikibooks.org/wiki/Programmation_Ada/FAQ/Généralités
> […] un retour à la ligne toutes les 72 colonnes, […]
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-24 5:13 ` Yannick Duchêne (Hibou57)
@ 2011-01-24 8:29 ` Yannick Duchêne (Hibou57)
0 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-01-24 8:29 UTC (permalink / raw)
Le Mon, 24 Jan 2011 06:13:13 +0100, Yannick Duchêne (Hibou57)
<yannick_duchene@yahoo.fr> a écrit:
> Le Wed, 19 Jan 2011 11:04:42 +0100, Dmitry A. Kazakov
> <mailbox@dmitry-kazakov.de> a écrit:
>>> I feel we could agree we could go beyond 80 characters (seems OK). But
>>> 120
>>> is too much. Well, let say 100 (cheese).
>>
>> I stick to my 72.
> According to the french version of the comp.lang.ada's FAQ, postings to
> the Usenet should be laid out using 72 characters wide lines:
> http://fr.wikibooks.org/wiki/Programmation_Ada/FAQ/Généralités
>> […] un retour à la ligne toutes les 72 colonnes, […]
OTH, http://www.ada-auth.org/standards/12rm/html/RM-2-2.html
says
> 14 An implementation shall support lines of at least 200 characters in
> length, not counting any characters used to signify the end of a line.
> An implementation shall support lexical elements of at least 200
> characters
> in length. The maximum supported line length and lexical element length
> are implementation defined.
Up to 200 characters… (even for a single lexical element)
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 13:17 ` Georg Bauhaus
2011-01-19 21:56 ` Yannick Duchêne (Hibou57)
@ 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 19:59 ` Yannick Duchêne (Hibou57)
2 siblings, 2 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-03-16 18:28 UTC (permalink / raw)
Le Wed, 19 Jan 2011 14:17:56 +0100, Georg Bauhaus
<rm.dash-bauhaus@futureapps.de> a écrit:
> On 19.01.11 12:42, Yannick Duchêne (Hibou57) wrote:
>
>> According to the authoritative FunnelWeb documentation, which you can
>> access
>> here:
>> http://www.ross.net/funnelweb/tutorial/intro_hello.html
>> the body of a macros, whose purpose is to expand into program text, is
>> exactly
>> the same as the one you suggested!
>
> No, no, the brackets @{ @}, or the line-of-code indicator @@ are much
> simpler than FunnelWeb. For one thing, the Ada programmer only needs
> to understand Ada and will not think about typesetting or macros or
> line endings.
>
Still in this area of annotations and rich documenting, I found another
more or less standard which could be of interest :
http://en.wikipedia.org/wiki/Epydoc
http://epydoc.sourceforge.net/
http://epydoc.sourceforge.net/manual-fields.html
Wikipedia says
> Epydoc is a documentation generator that processes its own lightweight
> markup language Epytext for Python documentation strings. As opposed to
> freeform Python docstrings, reStructured Text (both also supported) and
> other markup languages for docstrings, Epytext supports linking between
> different pieces of documentation.
What I particularly enjoy here, is the part “supports linking between
different pieces of documentation”.
While there are multiple standards covering similar things (I would like
one single standard, not many), there is at least one aspect which seems
there all the time : the meaning of “@” as introducing annotations. You
got it in Java, C, Python, FunnelWeb, among others. That's widely used
enough. At least a step to something standard… (I still miss many and many
things).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-19 13:17 ` Georg Bauhaus
2011-01-19 21:56 ` Yannick Duchêne (Hibou57)
2011-03-16 18:28 ` Yannick Duchêne (Hibou57)
@ 2011-03-16 19:59 ` Yannick Duchêne (Hibou57)
2 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-03-16 19:59 UTC (permalink / raw)
Le Wed, 19 Jan 2011 14:17:56 +0100, Georg Bauhaus
<rm.dash-bauhaus@futureapps.de> a écrit:
> For one thing, the Ada programmer only needs
> to understand Ada and will not think about typesetting or macros or
> line endings.
One you may enjoy in that purpose, is NaturalDoc, because it seems they
focused on the requirement for the documentation to look as much natural
as possible. Have a look :
http://www.naturaldocs.org/documenting.html
And this comes with support for Ada (among many others).
I feel a bit lost between these two options : have an explicit mark up for
metadatas and annotations (like Doxygen do), which allows more reacher and
precise semantic, and something which looks more natural (like NaturalDoc
do), but for that reason, with more easily reached limits (as to be more
precise, you need more specific notations).
Do you see the point ? Do you have some thoughts about ?
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-03-16 18:28 ` Yannick Duchêne (Hibou57)
@ 2011-03-16 20:13 ` Shark8
2011-03-16 21:51 ` Randy Brukardt
1 sibling, 0 replies; 96+ messages in thread
From: Shark8 @ 2011-03-16 20:13 UTC (permalink / raw)
On Mar 16, 12:28 pm, Yannick Duchêne (Hibou57)
<yannick_duch...@yahoo.fr> wrote:
> Le Wed, 19 Jan 2011 14:17:56 +0100, Georg Bauhaus
> <rm.dash-bauh...@futureapps.de> a écrit:
>
> > On 19.01.11 12:42, Yannick Duchêne (Hibou57) wrote:
>
> >> According to the authoritative FunnelWeb documentation, which you can
> >> access
> >> here:
> >>http://www.ross.net/funnelweb/tutorial/intro_hello.html
> >> the body of a macros, whose purpose is to expand into program text, is
> >> exactly
> >> the same as the one you suggested!
>
> > No, no, the brackets @{ @}, or the line-of-code indicator @@ are much
> > simpler than FunnelWeb. For one thing, the Ada programmer only needs
> > to understand Ada and will not think about typesetting or macros or
> > line endings.
>
> Still in this area of annotations and rich documenting, I found another
> more or less standard which could be of interest :http://en.wikipedia.org/wiki/Epydochttp://epydoc.sourceforge.net/http://epydoc.sourceforge.net/manual-fields.html
>
> Wikipedia says> Epydoc is a documentation generator that processes its own lightweight
> > markup language Epytext for Python documentation strings. As opposed to
> > freeform Python docstrings, reStructured Text (both also supported) and
> > other markup languages for docstrings, Epytext supports linking between
> > different pieces of documentation.
>
> What I particularly enjoy here, is the part “supports linking between
> different pieces of documentation”.
>
> While there are multiple standards covering similar things (I would like
> one single standard, not many), there is at least one aspect which seems
> there all the time : the meaning of “@” as introducing annotations. You
> got it in Java, C, Python, FunnelWeb, among others. That's widely used
> enough. At least a step to something standard… (I still miss many and many
> things).
>
> --
> Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
> les chiens.
>
> “I am fluent in ASCII” [Warren 2010]
And in the TP-world '@' is the "address of" operator.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
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)
1 sibling, 1 reply; 96+ messages in thread
From: Randy Brukardt @ 2011-03-16 21:51 UTC (permalink / raw)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 837 bytes --]
"Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> wrote in message
news:op.vsf79rhwule2fv@index.ici...
...
>While there are multiple standards covering similar things (I would like
>one single standard, not many), there is at least one aspect which seems
>there all the time : the meaning of "@" as introducing annotations. You
>got it in Java, C, Python, FunnelWeb, among others. That's widely used
>enough. At least a step to something standard. (I still miss many and many
>things).
Janus/Ada has used "@" as the conditional compilation character since it was
created. (It is either treated as a space or a comment symbol ("--")
depending on the compiler switches.) So you'll find lots of '@' in Janus/Ada
source code, and what follows it has little to do with annotations.
Randy.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-03-16 21:51 ` Randy Brukardt
@ 2011-03-16 22:01 ` Yannick Duchêne (Hibou57)
2011-03-19 1:47 ` Randy Brukardt
0 siblings, 1 reply; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-03-16 22:01 UTC (permalink / raw)
Le Wed, 16 Mar 2011 22:51:05 +0100, Randy Brukardt <randy@rrsoftware.com>
a écrit:
> Janus/Ada has used "@" as the conditional compilation character since it
> was
> created. (It is either treated as a space or a comment symbol ("--")
> depending on the compiler switches.) So you'll find lots of '@' in
> Janus/Ada
> source code, and what follows it has little to do with annotations.
>
> Randy.
What are your personal suggestions there ? Do you use any kind of helpers
to get human readable documentation texts and sources synchronized ? (this
is worded this way, with emphases on synchronization, because there is not
formally any requirement for this to be all written inside the source
only).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“I am fluent in ASCII” [Warren 2010]
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-03-16 22:01 ` Yannick Duchêne (Hibou57)
@ 2011-03-19 1:47 ` Randy Brukardt
0 siblings, 0 replies; 96+ messages in thread
From: Randy Brukardt @ 2011-03-19 1:47 UTC (permalink / raw)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2614 bytes --]
"Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> wrote in message
news:op.vsgh49tfule2fv@index.ici...
>Le Wed, 16 Mar 2011 22:51:05 +0100, Randy Brukardt <randy@rrsoftware.com>
a �crit:
>> Janus/Ada has used "@" as the conditional compilation character since it
>> was
>> created. (It is either treated as a space or a comment symbol ("--")
>> depending on the compiler switches.) So you'll find lots of '@' in
>> Janus/Ada
>> source code, and what follows it has little to do with annotations.
>
>What are your personal suggestions there ? Do you use any kind of helpers
>to get human readable documentation texts and sources synchronized ? (this
>is worded this way, with emphases on synchronization, because there is not
>formally any requirement for this to be all written inside the source
>only).
For Claw, we created a tool that processes the public specifications
(including the comments) and turns them into HTML/RTF documentation. That
documentation has an intermediate representation that can be hand-edited (to
improve the format of the comments -- they're marked up in a similar way to
the way the !corrigendum sections are marked up in AIs -- what a surprise
:-), and a mechanism to update the intermediate without clobbering the
hand-edits.
It proved to be too complex in practice; I doubt I would use it again.
What I'd probably do today is define a documentation aspect (probably
formatted in HTML) and make that an intergral part of the source code. That
would take advantage of the permission added to Ada 2012 during yesterday's
phone meeting (how's that for up-to-the minute changes??) for compiler
writer's to add implementation-defined aspects of their own design and
syntax to Ada 2012.
Of course this requires getting support for that added to your favorite Ada
compiler (I have a distinct advantage there); a tool to produce code without
the aspect (so the code can be ported to another compiler) [also pretty
easy, of course], and preferably some support in the IDE.
To do something portable, you'd have to do something similar in Ada
comments. That means defining a special comment symbol to mark your
formatted documentation, and again preferably some IDE support (especially
so that the documentation doesn't overwhelm the code).
I don't think separate files are really practical, with the possible
exception of something that is managed automatically by an IDE. It's just
too hard to keep them in synch. (And of course, if you have to depend on IDE
support, it will only work on that IDE.)
Randy.
^ permalink raw reply [flat|nested] 96+ messages in thread
* Re: AWS Coding Styles (and about boring plain-linear text files in the end)
2011-01-17 10:23 ` pascal.obry
2011-01-17 10:49 ` Simon Wright
2011-01-18 19:07 ` Florian Weimer
@ 2011-05-25 20:43 ` Yannick Duchêne (Hibou57)
2 siblings, 0 replies; 96+ messages in thread
From: Yannick Duchêne (Hibou57) @ 2011-05-25 20:43 UTC (permalink / raw)
Le Mon, 17 Jan 2011 11:23:12 +0100, pascal.obry@gmail.com
<pascal.obry@gmail.com> a écrit:
>> 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).
>
> 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.
This also force consistency, because without a prior declaration,
subprograms which are specific to package body comments about the
signature comes with the subprogram implementation, while comments about
the signature of subprograms defined in the specification, comes at the
signature declaration. This lead to inconsistent layout, so it is indeed
better for this second reason two : comments always comes with
specification, instead of some with specification and some with
implementation.
Another third reason, is that this more clearly emphases distinction
between subprograms specific to package body and the others. Without this,
if one meet a subprogram implementation, he/she don't know if this
subprogram in internal or defined in the specification.
About the latter: this makes me recall it happens I feel this may be an
idea to have a way to clearly mark (a keyword ?) a subprogram
implementation as being the one of a subprogram declared in a package
specification or not. This could improve readability, especially when
defensive programming is a concern. Or… alternatively, smart enough
editors could automatically tag this, and make this tag clearly visible
within the UI (ASIS could help).
--
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour
les chiens.
“ c++; /* this makes c bigger but returns the old value */ ” [Anonymous]
^ permalink raw reply [flat|nested] 96+ messages in thread
end of thread, other threads:[~2011-05-25 20:43 UTC | newest]
Thread overview: 96+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-01-17 5:07 AWS Coding Styles (and about boring plain-linear text files in the end) Yannick Duchêne (Hibou57)
2011-01-17 5:18 ` 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)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox