AWS Coding Styles (and about boring plain-linear text files in the end)

AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Shark8]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[pascal.obry]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Simon Wright]

"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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[pascal.obry]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Florian Weimer]

* 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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Florian Weimer]

* 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!

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Simon Wright]

"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?

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Simon Wright]

"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...

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Peter C. Chapin]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Florian Weimer]

* 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.)

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

"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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Pascal Obry]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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?"

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Randy Brukardt]

"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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[J-P. Rosen]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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...)

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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.)

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Shark8]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Randy Brukardt]

[-- 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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Randy Brukardt]

[-- 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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Bill Findlay]

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;

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Simon Wright]

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!

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Simon Wright]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Bill Findlay]

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;

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[pascal.obry]

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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

"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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Dmitry A. Kazakov]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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...

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[sjw]

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 ..

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Bill Findlay]

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;

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Pascal Obry]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Thomas Løcke]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Peter C. Chapin]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Randy Brukardt]

[-- 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] 

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[tmoran]

> 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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Randy Brukardt]

<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.

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Georg Bauhaus]

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...

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[J-P. Rosen]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[J-P. Rosen]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

"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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Dmitry A. Kazakov]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Dmitry A. Kazakov]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[J-P. Rosen]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Dmitry A. Kazakov]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[J-P. Rosen]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Dmitry A. Kazakov]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Dmitry A. Kazakov]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Robert Matthews]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Jeffrey Carter]

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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Stephen Leake]

"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

Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Yannick Duchêne (Hibou57)]

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]