Case dependence and coding standards

Case dependence and coding standards

[Fionn mac Cuimhaill]

With regards to the thread about case dependence - no, no, a thousand
times no! Keep Ada the way it is. I *would* like to see a fairly
simple way of getting the compiler to enforce coding standards. I
frequently annoy myself  by  writing something like Put_line when I
intended to to write Put_Line. It would be nice to be able to specify
some kind of coding standard dictionary as an appendage to a package
or procedure.

The source code of the dictionary could use an Ada-like syntax. For
example, consider a package named My_Package.

A coding standard dictionary might look something like this:


-- Coding standards for XYZ Software, Inc. 

dictionary My_Package is

    -- Identifiers not in the dictionary
    -- Look_Like_This
    default  mixed; 

    -- reserved words must be uppercase; if
    -- this is not specified, everything would be mixed
    reserved upper;
    
begin
  
  -- the first itemis not case
  -- sensitive; the second one
  -- is, and the compiler enforces it on
  -- the source code
  my_io_routine: My_IO_Routine;
  xyz_container: XYZ_Container;

end My_Package;

My_Package could of course be a parent to other packages, such as
My_Package.Child_Package; We could then have

dictionary My_Package.Child_Package is

    default upper;
    -- legal parameters for the default statement
    -- would be upper, lower, mixed, parent
    -- value parent means inherit
    -- value used by the parent package;
    -- it would not be allowed in dictionaries
    -- of packages that had no parents.

    -- compiler or editor/IDE enforces
    -- My_Package.MY_IDENTIFIER
    
begin
    ubig: uBIG;
    usmall: uSMALL;
end My_Package.Child_Package;

This would be way of specifying coding standards that would be
compiler-independent and editor/IDE independent and could be enforced
by either.

GNAT, which puts one package to a source file, could then have a .dic
file to go with the .ads and .adb file for a package. Gnatstub could
make a .dic file when it makes a .adb file. Gnatmake could force a
recheck of source code if the .dic file changes. And so forth ...

A future version of AdaGIDE could use the .dic file to drive automatic
formatting, as could future versions of EMACS, vim or JED. (if the
maintainers of those are sufficiently interested) Programmers 
could use their pet editors and still get the benefit of common
standards, automatically enforced.

Since this would have very little interaction with language standards,
the dictionary language could be standardized independently of Ada
itself.

Re: Case dependence and coding standards

[Robert A Duff]

Fionn mac Cuimhaill <invisible@hiding.from.spam> writes:

> With regards to the thread about case dependence - no, no, a thousand
> times no! Keep Ada the way it is. I *would* like to see a fairly
> simple way of getting the compiler to enforce coding standards.

GNAT has a switch that requires a reference to a declaration to
case-match the declaration.  That seems like a good idea, and is much
simpler than the "dictionary" idea you outlined.

Furthermore, there is no advantage to having some folks use upper case
for reserved words.  The standard advises lower case, and if you do
differently, you make the code harder to read for folks used to the
standard convention.

>...I
> frequently annoy myself  by  writing something like Put_line when I
> intended to to write Put_Line.

GNAT would complain about this (under the switch).

It would be nicer to have a compiler that simply corrected such errors
in the source file, instead of complaining about them.  The goal is to
make consistent/readable code, not to punish programmers who are too
lazy to hit the shift key.

- Bob

Re: Case dependence and coding standards

[Vinzent Hoefler]

Robert A Duff wrote:

>It would be nicer to have a compiler that simply corrected such errors
>in the source file, instead of complaining about them.

Well, I expect a compiler to *read* the source, not actually *write*
it.

>The goal is to make consistent/readable code,

Strong ACK.

>not to punish programmers who are too
>lazy to hit the shift key.

NAK. Lazyness has to be punished. Hard. ;->


Vinzent.

-- 
Parents strongly cautioned  --  this  posting  is  intended for mature
audiences  over  18.  It  may  contain some material that many parents
would not find suitable for children and may include intense violence,
sexual situations, coarse language and suggestive dialogue.

Re: Case dependence and coding standards

[Robert A Duff]

Vinzent Hoefler <ada.rocks@jlfencey.com> writes:

> Robert A Duff wrote:
> 
> >It would be nicer to have a compiler that simply corrected such errors
> >in the source file, instead of complaining about them.
> 
> Well, I expect a compiler to *read* the source, not actually *write*
> it.

Sure, that's what we're all used to.  But we expect our editors and
pretty-printers and CM systems and so forth to modify our source code.
Why do we trust some programs over others to modify our code?

I like to turn on the GNAT switch that complains when I say "Text_io"
instead of "Text_IO".  The latter is more readable, because that's how
the package was declared.  But I would like even better for it to fix
it, rather than complain about it.

Of course, Emacs does almost all of that for me, as I type it in, but in
a few cases it requires extra work -- Emacs doesn't know Ada visibility
and overloading rules.

> >The goal is to make consistent/readable code,
> 
> Strong ACK.

:-)

> >not to punish programmers who are too
> >lazy to hit the shift key.
> 
> NAK. Lazyness has to be punished. Hard. ;->

On the contrary.  Laziness should be encouraged, in the sense of
programmers avoiding useless work.  The only kind of laziness I want
to inhibit is the kind that causes extra work in the long run
(e.g. unreadable code).

- Bob

Re: Case dependence and coding standards

[Stephen Leake]

Robert A Duff <bobduff@shell01.TheWorld.com> writes:

> (snip stuff about case errors)
> 
> It would be nicer to have a compiler that simply corrected such errors
> in the source file, instead of complaining about them.  The goal is to
> make consistent/readable code, not to punish programmers who are too
> lazy to hit the shift key.

That's what compilers integrated into IDE's are for. For GNAT under
Emacs or GPS, when the compiler complains about a case mismatch, you
hit a key, and the editor fixes it (it reads the compiler's error
message to know what to do).

Sometimes, of course, it's the defining instance that's wrong, so the
compiler error message contains info on where that is, so you can get
to it easily.

In my Emacs, F6 is bound to 'next-error', and C-F6 to 'gnat-fix-error'.
It's amazing how many times I just hit F6, C-F6 to get thru all the
error messages. Kind of fun :).

-- 
-- Stephe

Re: Case dependence and coding standards

[Randy Brukardt]

Robert A Duff wrote in message ...
>Vinzent Hoefler <ada.rocks@jlfencey.com> writes:
>> Well, I expect a compiler to *read* the source, not actually *write*
>> it.
>
>Sure, that's what we're all used to.  But we expect our editors and
>pretty-printers and CM systems and so forth to modify our source code.
>Why do we trust some programs over others to modify our code?


Immediate feedback in an IDE, as opposed to some batch process where the
changes (for good or evil) are hidden away.

I *don't* allow pretty-printers and CM systems to modify my code; my
experience is that they make it worse as often as they make it better.
(The inability to turn off Rational's pretty printer in their editor is
a great frustration to me.) I don't even think it is possible to write a
pretty printer that will do a good job in general; such programs can't
know when to line up declarations and when not to; when to leave
comments alone and when to reformat them; and so on. (And I've tried to
write one; you'll find it in Janus/Ada.)

So I certainly would not want or allow a compiler to modify my code. The
IDE can do such things (but it needs to be configurable in many ways,
and it has to allow writing whatever makes sense, even if it violates
some rule in the IDE's formatter).

            Randy.

Re: Case dependence and coding standards

[Wesley Groleau]

> I *don't* allow pretty-printers and CM systems to modify my code; my
> experience is that they make it worse as often as they make it better.

Often true--not always.  I use to call the one in Apex
the "ugly-printer" but they've considerably improved it.

> (The inability to turn off Rational's pretty printer in their editor is
> a great frustration to me.) I don't even think it is possible to write a

Yes, it can be turned off.  And it's behavior can be modified
by view switches and/or environment variables.

> pretty printer that will do a good job in general; such programs can't
> know when to line up declarations and when not to; when to leave

Rational's pretty-printer as of 4.2 can vertically align all of:

:=  in  out  =>  :  --    (although it's still not perfect)

In version 3.2, if you put two spaces at the end of a line,
it would somewhat preserve your own alignment.  If I remember
right, Ada-ASSURED can do vertical alignment also.

> comments alone and when to reformat them; and so on. (And I've tried to
> write one; you'll find it in Janus/Ada.)

I can't remember whether Ada-ASSURED can do this.
Seems to me I've seen one somewhere that can do it.

Re: Case dependence and coding standards

[Vinzent Hoefler]

Robert A Duff wrote:

>Vinzent Hoefler <ada.rocks@jlfencey.com> writes:
>
>> Robert A Duff wrote:
>> 
>> >It would be nicer to have a compiler that simply corrected such errors
>> >in the source file, instead of complaining about them.
>> 
>> Well, I expect a compiler to *read* the source, not actually *write*
>> it.
>
>Sure, that's what we're all used to.  But we expect our editors and
>pretty-printers and CM systems and so forth to modify our source code.

Well, let's say it so: I expect it changes the source in the way I
intended to change the source by hacking on some keys, but never
automatically.

>I like to turn on the GNAT switch that complains when I say "Text_io"
>instead of "Text_IO".

Yes, me too. And then I fix such typos by hand.

>  The latter is more readable, because that's how
>the package was declared.  But I would like even better for it to fix
>it, rather than complain about it.

Well, I wouldn't like it. I would expect that a command like
"pretty-print foobar.adb" to do, but not the compiler. Sometimes
source files that I wish to be compiled aren't even writable.

>> >not to punish programmers who are too
>> >lazy to hit the shift key.
>> 
>> NAK. Lazyness has to be punished. Hard. ;->
>
>On the contrary.  Laziness should be encouraged, in the sense of
>programmers avoiding useless work.

Perhaps we are talking about different kinds of laziness here. :)

>  The only kind of laziness I want
>to inhibit is the kind that causes extra work in the long run
>(e.g. unreadable code).

Yes, but I don't see, how not hitting the shift-key at the appropriate
time to generate readable code isn't laziness. Yeah, I know typos are
the usual suspects, but fixing them automatically would encourage the
coder to never use the shift key, because "the compiler fixes it
anyway". That's laziness and is contrary to my opinion that the code
has to be readable from the very first start.

Its kind of the same problem why quick fixes (aka. dirty hacks) become
standard some months later... ;)


Vinzent.

-- 
Parents strongly cautioned  --  this  posting  is  intended for mature
audiences  over  18.  It  may  contain some material that many parents
would not find suitable for children and may include intense violence,
sexual situations, coarse language and suggestive dialogue.

Re: Case dependence and coding standards

[Georg Bauhaus]

Wesley Groleau <wesgroleau@despammed.com> wrote:
: Rational's pretty-printer as of 4.2 can vertically align all of:
: 
: :=  in  out  =>  :  --    (although it's still not perfect)

Tabular	layout	may	or	may	not	be	an
advantage	,	I	am	still	eager	to
hear	arguments	,	other	than	tired	programmers
liking	the	tidy	look	of	it	.

Georg

Re: Case dependence and coding standards

[Preben Randhol]

Georg Bauhaus wrote:
> Wesley Groleau <wesgroleau@despammed.com> wrote:
>: Rational's pretty-printer as of 4.2 can vertically align all of:
>: 
>: :=  in  out  =>  :  --    (although it's still not perfect)
> 
> Tabular	layout	may	or	may	not	be	an
> advantage	,	I	am	still	eager	to
> hear	arguments	,	other	than	tired	programmers
> liking	the	tidy	look	of	it	.

Only place I think it may be useful is to do something like below:

procedure Many_Things
   (Text : out String;
    Amount : in Natural;
    Transform : in Boolean;
    Prefix : in String := "");

using tabs (although I alsways use spaces and 3 is max) makes it a bit
easier to read IMHO

procedure Many_Things
   (Text      : out String;
    Amount    : in  Natural;
    Transform : in  Boolean;
    Prefix    : in  String := "");

This too.

procedure Many_Things
   (Text      :    out String;
    Amount    : in     Natural;
    Transform : in     Boolean;
    Prefix    : in     String := "");

-- 
Preben Randhol                    http://www.pvv.org/~randhol/

Re: Case dependence and coding standards

[Stephen Leake]

Vinzent Hoefler <ada.rocks@jlfencey.com> writes:

> Robert A Duff wrote:
> 
> >Vinzent Hoefler <ada.rocks@jlfencey.com> writes:
> >
> >> Robert A Duff wrote:
> >> 
> >> >It would be nicer to have a compiler that simply corrected such errors
> >> >in the source file, instead of complaining about them.
> >> 
> >> Well, I expect a compiler to *read* the source, not actually *write*
> >> it.
> >
> >Sure, that's what we're all used to.  But we expect our editors and
> >pretty-printers and CM systems and so forth to modify our source code.
> 
> Well, let's say it so: I expect it changes the source in the way I
> intended to change the source by hacking on some keys, but never
> automatically.
> 
> >I like to turn on the GNAT switch that complains when I say "Text_io"
> >instead of "Text_IO".
> 
> Yes, me too. And then I fix such typos by hand.

Wouldn't you like your IDE to have a command to fix it for you? (like
Emacs and GPS).

> <snip>
> 
> >  The only kind of laziness I want
> >to inhibit is the kind that causes extra work in the long run
> >(e.g. unreadable code).
> 
> Yes, but I don't see, how not hitting the shift-key at the appropriate
> time to generate readable code isn't laziness. Yeah, I know typos are
> the usual suspects, but fixing them automatically would encourage the
> coder to never use the shift key, because "the compiler fixes it
> anyway". That's laziness and is contrary to my opinion that the code
> has to be readable from the very first start.

I agree that "code has to be readable". But I don't impose that
requirement until after it compiles. Since we rely on the compiler to
catch type and syntax errors, why not also rely on it to catch
capitalization errors?

The goal is overall productivity; how fast I can write good code. It's
faster for me to not worry about hitting the space bar, as long as the
editor and compiler either do it for me or make it very easy to detect
and fix case errors. And yes, _thinking_ about what the capitalization
of an identifier should be takes mental cycles that can be better
spent thinking about the problem solution.

> Its kind of the same problem why quick fixes (aka. dirty hacks)
> become standard some months later... ;)

I disagree. The compiler enforces capitalization, in the same way it
enforces syntax rules. I'm trading brain cycles for CPU cycles, and I
see a net gain. Since I now have more brain cycles available, dirty
hacks are less likely.

-- 
-- Stephe

RE: Case dependence and coding standards

[Lionel.DRAGHI]

| -----Message d'origine-----
| De: Robert A Duff [mailto:bobduff@shell01.TheWorld.com]
...
| 
| It would be nicer to have a compiler that simply corrected such errors
| in the source file, instead of complaining about them.  The goal is to
| make consistent/readable code, not to punish programmers who are too
| lazy to hit the shift key.
With the ada-mode case exception file, they don't even need to hit the shift
key. 

They just need to hit some key on the first occurence of (for example) "IO",
and further Text_IO, Direct_IO and so on will be formated automaticaly.

-- 
Lionel Draghi

Re: Case dependence and coding standards

[Wesley Groleau]

Georg Bauhaus wrote:
> Wesley Groleau <wesgroleau@despammed.com> wrote:
> : Rational's pretty-printer as of 4.2 can vertically align all of:
> : 
> : :=  in  out  =>  :  --    (although it's still not perfect)
> 
> Tabular	layout	may	or	may	not	be	an
> advantage	,	I	am	still	eager	to
> hear	arguments	,	other	than	tired	programmers
> liking	the	tidy	look	of	it	.
> 
> Georg

First, I mentioned that it can vertically align
a certain set of symbols in source code, not all
words in English prose.

Second, source code does not contain multiple
words in prose style.

Third,

     Variable : Variable_Type;  -- does the one thing
     Another_Variable : Another_Variable_Type; -- does the other thing

IS a table in nature:
   first column      - object name;
   second column     - object type;
   third column      - clarification;
   column separators - ':' and '--'

Makes sense to me to write it like one:

     Variable         : Variable_Type;         -- number of doohickies built
     Another_Variable : Another_Variable_Type; -- the current one built here

Same meaning to the compiler, MUCH easier on the human reader.
Notice that I never intended screwing up the comments as your
strawman suggests.

There is precedent for doing the same thing even in prose.
Look at the section starting with uppercase IS.  When I was
a technical writer, I would never have handed to the editor
something like that formatter like this:

IS a table in nature: first column is object name, second
column is object type, third column is clarification, and
the column separators are the colons and the double hyphens.

Re: Case dependence and coding standards

[Robert I. Eachus]

Stephen Leake wrote:

> I disagree. The compiler enforces capitalization, in the same way it
> enforces syntax rules. I'm trading brain cycles for CPU cycles, and I
> see a net gain. Since I now have more brain cycles available, dirty
> hacks are less likely.

Personally, I am comfortable with using "pretty printers" through some 
stage of the procedings, and from then on I do like the GNAT behavior of 
treating capitalization errors as errors.  They are, but the compiler 
can't be sure what the error is, just that there is one.  So it 
shouldn't "fix" it silently.  As I said, beyond a certain point I want 
to control all changes to the code myself.

Re: Case dependence and coding standards

[Vinzent Hoefler]

Stephen Leake wrote:

>Vinzent Hoefler <ada.rocks@jlfencey.com> writes:
>
>> Robert A Duff wrote:
>> 
>> >I like to turn on the GNAT switch that complains when I say "Text_io"
>> >instead of "Text_IO".
>> 
>> Yes, me too. And then I fix such typos by hand.
>
>Wouldn't you like your IDE to have a command to fix it for you? (like
>Emacs and GPS).

Yes, because then I am the one who changes the codes willingly.

>> Yes, but I don't see, how not hitting the shift-key at the appropriate
>> time to generate readable code isn't laziness. Yeah, I know typos are
>> the usual suspects, but fixing them automatically would encourage the
>> coder to never use the shift key, because "the compiler fixes it
>> anyway". That's laziness and is contrary to my opinion that the code
>> has to be readable from the very first start.
>
>I agree that "code has to be readable". But I don't impose that
>requirement until after it compiles.

Well, I think, typing it right in the first place would help the
programmer, too.

>Since we rely on the compiler to
>catch type and syntax errors, why not also rely on it to catch
>capitalization errors?

Well, it *catches* them. But it shouldn't fix them.

>The goal is overall productivity; how fast I can write good code.

Well, that is a point. But I don't type in a compiler (unless someone
is crazy enough to tell the compiler to use standard input...).

OTOH, usually pure coding only takes a relatively small amount of time
of the whole development process, so the advantage of fast typing
isn't that much. If that would be, we should all take secretary
lessons to type in 10-finger-system. I never had such lesson, compared
to the usual secretary I'm typing darn slow, although I'd say, my
productivity is still good.

>It's
>faster for me to not worry about hitting the space bar, as long as the
>editor and compiler either do it for me or make it very easy to detect
>and fix case errors.

Well, if the IDE fixes it, this is ok. Although I wouldn't like to fix
it automatically.

Indeed, after trying out Word sometimes, I have the strong feeling
that turning on the automatic spelling correction (or whatever it is
called) actually *slowed* down by process of typing. Well, programming
languages are much more strict than the usual documentation or letters
(especially because Word doesn't know of all the technical terms I may
use), so this probably really isn't comparable.

>And yes, _thinking_ about what the capitalization
>of an identifier should be takes mental cycles that can be better
>spent thinking about the problem solution.

I don't know. Never took the measurement, it's hard to measure brain
cycles. :) But sometimes I even reformat old code while reviewing and
enhance it both visually and in terms of robustness. I don't have the
feeling that it takes me longer to do so in the end.

Hmm. Ok, you're right, if it's just to make sure of a consistent
capitalization, this is usually a search and replace tasks that should
be left to the machine.

>> Its kind of the same problem why quick fixes (aka. dirty hacks)
>> become standard some months later... ;)
>
>I disagree. The compiler enforces capitalization, in the same way it
>enforces syntax rules.

Ok, you're right.

The result would be the same in terms of maintainance, because the
other coders actually never see what kind of crap someone typed into
the editor before... ;)

>I'm trading brain cycles for CPU cycles, and I
>see a net gain.

Well, I agree with you, if the IDE would fix it instantly. But if I
would type

for foo in bar'range loop exit when baz<3; end loop;

or such and then trust the compiler to fix it I would have a hard time
understanding the code that I write. And I think, the more I type it
right in the first place, then it is less likely that the compiler
will complain about some stupid errors like a missing semicolon. So I
see a net gain here in less editor-compiler cycles. YMMV.

>Since I now have more brain cycles available, dirty
>hacks are less likely.

Well, my brain would be more stressed with seeing such code, lowering
the performance for the task to make the code correct in the first
place. ;)


Vinzent.

-- 
Parents strongly cautioned  --  this  posting  is  intended for mature
audiences  over  18.  It  may  contain some material that many parents
would not find suitable for children and may include intense violence,
sexual situations, coarse language and suggestive dialogue.

Re: Case dependence and coding standards

[Georg Bauhaus]

Wesley Groleau <wesgroleau@despammed.com> wrote:
: Georg Bauhaus wrote:
:> Wesley Groleau <wesgroleau@despammed.com> wrote:
:> : Rational's pretty-printer as of 4.2 can vertically align all of:
:> : 
:> : :=  in  out  =>  :  --    (although it's still not perfect)
:> 
:> Tabular       layout  may     or      may     not     be      an
:> advantage     ,       I       am      still   eager   to
:> hear  arguments       ,       other   than    tired   programmers
:> liking        the     tidy    look    of      it      .
:> 
:> Georg
: 
: First, I mentioned that it can vertically align
: a certain set of symbols in source code, not all
: words in English prose.
: 
: Second, source code does not contain multiple
: words in prose style.

Yes, but it might still be read, see below.

: 
: Third,
: 
:     Variable : Variable_Type;  -- does the one thing
:     Another_Variable : Another_Variable_Type; -- does the other thing
: 
: IS a table in nature:
:   first column      - object name;
:   second column     - object type;
:   third column      - clarification;
:   column separators - ':' and '--'
: 
: Makes sense to me to write it like one:
: 
:     Variable         : Variable_Type;         -- number of doohickies built
:     Another_Variable : Another_Variable_Type; -- the current one built here
: 
: Same meaning to the compiler, MUCH easier on the human reader.

Here is where I'd like to see an argument, not a strong emphasis.
For another view (which empirically finds that layout-style guides
won't get you anywhere), see
http://www.cs.ukc.ac.uk/people/staff/lh8/pubs/pubist602s/MISRAC.pdf

There are different modes of reading source code.

One mode is when you use source code the way you look things up in
a table.  This might be the case when you vaguely remember an item,
and you want to look up the details, like the exact type or mode.
Another mode is when you start learning about an item and read all about it
from left to right, from top to bottom.

In the first case, I think tabular layout might help, but see below.
In the second case, the material to be read is closer to prose than
to a lookup table.

When I look at a time table, I can quickly scan a column for
2pm; when I am looking at the modes of subprogram parameters
vertically aligned in a column, what am I looking for? the
information seems incomplete to me, one column is not enough.
Still quickly finding just the modes might be useful in _some_ cases,
but then I'd prefer what is frequently done in print: make
them stand out using bold face type. As you have demonstrated,
humans can easily find out whether something is tabular in nature
_without_ "squarish" tabular layout, if "abstract" column separators
can easily be seen, like a ':'.

This might look like minor details, and I don't think these
particulars are important, but how about variable declarations,
consisting of name, type, constraints, and comment?  How about
constants, which add another column? Should a constraint that
might have three parts trigger tabular layout? Say you have

      north: Positive range 0 .. 90;  -- stops at north pole
      west: Positive range 0 .. 360; -- around the earth
      depth: Integer range -20_000 .. 0; -- below the sea

This could be formatted to look nicely ordered like

      north : Positive range       0 .. 90;   -- stops at north pole
      west  : Positive range       0 .. 360;  -- around the earth
      depth : Integer  range -20_000 .. 0;    -- below the sea

I wouldn't know how this could be extended consistently to include
constants (or longer identifiers). For a start, add:

      station_latitude: constant Mammoth_Footstep := 12;  -- where we are
 
If these four declarations should be grouped and alignments made at
':' etc, there will be a problem. 

After all I could argue that an if statement is a table in
nature too, like a case statement. Column borders: if, then, else, end.
Still, what kind of tabular layout is appropriate for an if statement?
I doubt programmers will like this idea.
Interestingly, it might be different with case statements where the cases
are short. But would you favour the use of "=>" after "when X"
as a column separator in the same way as ':' in variable declarations?
Sometimes I do that but usually I just use indentation and two or more
lines for a case, not a table. Here are some variations:

   declare
      X: Integer range 1..7;
   begin
      case X is
         when 1 => letsgo;
         when 2 .. 4 => come_on;
         when 5 => go_steady;
         when 6 | 7 => calm;
      end case;
   end;
   
   declare
      X: Integer range 1..7;
   begin
      case X is
         when 1      => letsgo;
         when 2 .. 4 => come_on;
         when 5      => go_steady;
         when 6 | 7  => calm;
      end case;
   end;

   declare
      X: Integer range 1..7;
   begin
      case X is
         when      1 => letsgo;
         when 2 .. 4 => come_on;
         when      5 => go_steady;
         when  6 | 7 => calm;
      end case;
   end;

   declare
      X: Integer range 1..7;
   begin
      case X is
         when   1    => letsgo;
         when 2 .. 4 => come_on;
         when   5    => go_steady;
         when 6 | 7  => calm;
      end case;
   end;

   declare
      X: Integer range 1..7;
   begin
      case X is
              when 1 => letsgo;
         when 2 .. 4 => come_on;
              when 5 => go_steady;
          when 6 | 7 => calm;
      end case;
   end;

: Notice that I never intended screwing up the comments as your
: strawman suggests.

It was not my intention to suggest that you screw up comments.

It's just that now and then I see source code where tabulation is
seemingly considered the essence of good coding. My eyes have to
jump "white gaps" of about 6em on the average on just about
every line. Now there _is_ (scientific) evidence that this is not
good for readers.

It might add to ones perspective to have a look a how Knuth's
C and Pascal programs look.


-- georg

Re: Case dependence and coding standards

[Preben Randhol]

Georg Bauhaus wrote:
> Here is where I'd like to see an argument, not a strong emphasis.

Cannot give you anything other than I find it easier to get an overview
of a function if it is lightly formated as I showed in my example. Other
may find that non formated is better.

>       north: Positive range 0 .. 90;  -- stops at north pole
>       west: Positive range 0 .. 360; -- around the earth
>       depth: Integer range -20_000 .. 0; -- below the sea

This is absolutly not nice. You should at least have a space after the
variable before the :. I would also want to format the comments out to
the side as they clutter the code. I don't like to use a lot of comments
at the end of the line.

         north : Positive range 0 .. 90;     -- stops at north pole
         west : Positive range 0 .. 360;     -- around the earth
         depth : Integer range -20_000 .. 0; -- below the sea


> This could be formatted to look nicely ordered like
> 
>       north : Positive range       0 .. 90;   -- stops at north pole
>       west  : Positive range       0 .. 360;  -- around the earth
>       depth : Integer  range -20_000 .. 0;    -- below the sea

I would have done:

       north : Positive range 0 .. 90;          -- stops at north pole
       west  : Positive range 0 .. 360;         -- around the earth
       depth : Integer  range -20_000 .. 0;     -- below the sea

if I wanted to format this.

-- 
Preben Randhol                    http://www.pvv.org/~randhol/

Re: Case dependence and coding standards

[Wesley Groleau]

Wesley Groleau wrote:
> a technical writer, I would never have handed to the editor
> something like that formatter like this:

oops: formatteD

Nor would I have handed in something I failed to proof-read!  :-)

Re: Case dependence and coding standards

[Wesley Groleau]

>>This could be formatted to look nicely ordered like
>>
>>      north : Positive range       0 .. 90;   -- stops at north pole
>>      west  : Positive range       0 .. 360;  -- around the earth
>>      depth : Integer  range -20_000 .. 0;    -- below the sea
> 
> I would have done:
> 
>        north : Positive range 0 .. 90;          -- stops at north pole
>        west  : Positive range 0 .. 360;         -- around the earth
>        depth : Integer  range -20_000 .. 0;     -- below the sea
> 
And I would have done:

    north : Positive range       0 ..  90;   -- stops at north pole
    west  : Positive range       0 .. 360;   -- around the earth
    depth : Integer  range -20_000 ..   0;   -- below the sea

But now we're getting a little bit picky.

There was a valid point that "searching" and "reading"
take different skills.  Indeed, it has been empirically
shown that searching is easier with ALL UPPER CASE
while reading is easier with mixed case.

But declarations are far more often used for searching than reading.
Even for reading, more often, tables are easier, I think.  (I don't
have empirical studies, though.)  The layout reduces the mental energy
in identifying the parts of the lookup.

Re: Case dependence and coding standards

[Preben Randhol]

Wesley Groleau wrote:
> Wesley Groleau wrote:
>> a technical writer, I would never have handed to the editor
>> something like that formatter like this:
> 
> oops: formatteD
> 
> Nor would I have handed in something I failed to proof-read!  :-)

Speaking of sensitivity. Python is indentation sensitive.

See:

   http://www.linuxjournal.com/article.php?sid=3882

Then search the page for "indentation error"

and you will see:

 if 'typemap' in class_sig:
 class_sig.remove('typemap')

and when I download and open the listing that has this error then all
indentations are a mess as they are a mix of TABs and spaces. 
(Well it was written by Eric Raymond so ...) Hopeless concept IMHO.

-- 
Preben Randhol                    http://www.pvv.org/~randhol/

Re: Case dependence and coding standards

[Preben Randhol]

Wesley Groleau wrote:
> have empirical studies, though.)  The layout reduces the mental energy
> in identifying the parts of the lookup.

That I agree with. A bunch of well formated function/procedure is less
stressful (I'm speaking of how I find this) than if it is not when I
want to find the function I need. I guess it has to do with that it is
easier to scimp a page that has a nice layout than otherwise.

-- 
Preben Randhol                    http://www.pvv.org/~randhol/

Re: Case dependence and coding standards

[Stephen Leake]

Vinzent Hoefler <ada.rocks@jlfencey.com> writes:

> Stephen Leake wrote:
> >The goal is overall productivity; how fast I can write good code.
> 
> Well, that is a point. 

Hey! Agreement in a newsgroup thread :).

> But I don't type in a compiler (unless someone is crazy enough to
> tell the compiler to use standard input...).

Close enough; you type in an editor, and the file is fed to the
compiler. 

> OTOH, usually pure coding only takes a relatively small amount of time
> of the whole development process, so the advantage of fast typing
> isn't that much. If that would be, we should all take secretary
> lessons to type in 10-finger-system. I never had such lesson, compared
> to the usual secretary I'm typing darn slow, although I'd say, my
> productivity is still good.

I disagree. I get very frustrated watching programmers who can't type
with all ten fingers. Take a lesson and see what you gain!

I don't have numbers, but I bet the time spent typing is about 10% of
my time on average (some of it in this newsgroup :). If I can cut that
to 8%, it's worth it.

> >It's faster for me to not worry about hitting the space bar, as
> >long as the editor and compiler either do it for me or make it very
> >easy to detect and fix case errors.
> 
> Well, if the IDE fixes it, this is ok. Although I wouldn't like to fix
> it automatically.

Well, I have Emacs set up so I type "text_io", and Emacs changes it to
"Text_IO". Sometimes it screws up, and I moan about it. Sometimes I
fix it. On the whole, I find it worth it.

> Indeed, after trying out Word sometimes, I have the strong feeling
> that turning on the automatic spelling correction (or whatever it is
> called) actually *slowed* down by process of typing. 

Yes, I hate the automatic capitalization in Word. That's because I'm
_not_ typing letters, which is Word is good for (yes, that's a very
strong and probably inaccurate statement. This isn't the MS Windows
newsgroup :). But I've taught Emacs to do a good job in helping me
write Ada code; that is the crucial difference.

> Well, programming languages are much more strict than the usual
> documentation or letters (especially because Word doesn't know of
> all the technical terms I may use), so this probably really isn't
> comparable.

Exactly.

> >And yes, _thinking_ about what the capitalization of an identifier
> >should be takes mental cycles that can be better spent thinking
> >about the problem solution.
> 
> I don't know. Never took the measurement, it's hard to measure brain
> cycles. :) But sometimes I even reformat old code while reviewing and
> enhance it both visually and in terms of robustness. I don't have the
> feeling that it takes me longer to do so in the end.

It is hard to measure. I decided a long time ago that fixing the IDE
was always worth it in the long run. So now, whenever I find myself
thinking "the computer could do this faster", I figure out how to make
that happen. If I get more people to use Emacs, the time savings is
magnified (yes, that is an ulterior motive :).

> Hmm. Ok, you're right, if it's just to make sure of a consistent
> capitalization, this is usually a search and replace tasks that should
> be left to the machine.

Wow! Twice in one posting :).
> 
> >> Its kind of the same problem why quick fixes (aka. dirty hacks)
> >> become standard some months later... ;)
> >
> >I disagree. The compiler enforces capitalization, in the same way it
> >enforces syntax rules.
> 
> Ok, you're right.
> 
> The result would be the same in terms of maintainance, because the
> other coders actually never see what kind of crap someone typed into
> the editor before... ;)
> 
> >I'm trading brain cycles for CPU cycles, and I
> >see a net gain.
> 
> Well, I agree with you, if the IDE would fix it instantly. But if I
> would type
> 
> for foo in bar'range loop exit when baz<3; end loop;
> 
> or such and then trust the compiler to fix it I would have a hard time
> understanding the code that I write. And I think, the more I type it
> right in the first place, then it is less likely that the compiler
> will complain about some stupid errors like a missing semicolon. So I
> see a net gain here in less editor-compiler cycles. YMMV.

Yes, I only let Emacs fix simple things like "text_io"; I still use
proper line breaks and indenting as I'm typing new code; although
Emacs does the indenting as well.

-- 
-- Stephe

Re: Case dependence and coding standards

[Preben Randhol]

Preben Randhol wrote:
> want to find the function I need. I guess it has to do with that it is
> easier to scimp a page that has a nice layout than otherwise.
            ^^^^^
            skim
-- 
Preben Randhol                    http://www.pvv.org/~randhol/

Re: Case dependence and coding standards

[Wesley Groleau]

> Still quickly finding just the modes might be useful in _some_ cases,
> but then I'd prefer what is frequently done in print: make
> them stand out using bold face type. As you have demonstrated,

Yes, that helps, too.

> humans can easily find out whether something is tabular in nature
> _without_ "squarish" tabular layout, if "abstract" column separators
> can easily be seen, like a ':'.

But they can do it with less mental energy if it is "squarish"
> particulars are important, but how about variable declarations,
> consisting of name, type, constraints, and comment?  How about
> constants, which add another column? Should a constraint that
> might have three parts trigger tabular layout? Say you have

Indeed, the more parts you have and the longer the names of the parts,
the harder it is to keep line length reasonable.  I generally consider
various options to get the layout that I feel is the least work for
an unfamilar person to understand.  It is subjective, but I think
my intuition is influenced by the empirical studies I've read on
readability and human factors, as well as by the numerous
misunderstandings I've witnessed people making on poorly formatted
code and technical prose, not only in software work, but in teaching
math, language, and electronics, and in reading and writing technical
material myself.

>       station_latitude: constant Mammoth_Footstep := 12;  -- where we are
>  
> If these four declarations should be grouped and alignments made at
> ':' etc, there will be a problem. 

Yes.  Sometimes you have to take another approach, as I've said above.
For this one (depending on what else is nearby), I'd probably put
separate it from the others with a blank line and format it differently.

> 
> After all I could argue that an if statement is a table in
> nature too, like a case statement. Column borders: if, then, else, end.
> Still, what kind of tabular layout is appropriate for an if statement?

Sure, but hardly ever are any of the parts short enough
to put side by side on a single line AND adjacent to another
such 'if' statement to make it worthwhile.

> Interestingly, it might be different with case statements where the cases
> are short. But would you favour the use of "=>" after "when X"
> as a column separator in the same way as ':' in variable declarations?

Yes, IF short enough.  This also is rare.  But when
it does happen, I do prefer one of the styles you offered:

>       case X is
>          when 1      => letsgo;
>          when 2 .. 4 => come_on;
>          when 5      => go_steady;
>          when 6 | 7  => calm;
>       end case;

> : Notice that I never intended screwing up the comments as your
> : strawman suggests.
> 
> It was not my intention to suggest that you screw up comments.

But your counterexample was prose such as would only occur
in comments.  Sorry if I misunderstood your intent.

Re: Case dependence and coding standards

[Wesley Groleau]

> I disagree. I get very frustrated watching programmers who can't type
> with all ten fingers. Take a lesson and see what you gain!

What if I have to hold open a reference with one hand
while with the other hand I type faster than some
people do with both hands?  :-)

I get frustrated when I see someone who refuses to learn
an editor other than 'vi' yet has never really learned
how to use 'vi'  (Deletes twenty lines by repeating 'x'
until the line is empty, going to the next line, and
doing it again.)

> Yes, I hate the automatic capitalization in Word. That's because I'm

That can be turned on and off.  I hate it, too.

---

The MISRA C article someone cited claims that
stylistic coding standards are useless because

(a) they are ignored and

(b) the things they prevent are not failures

_BUT_

(a) it also shows that an allegedly better standard
     that allegedly _only_ prevents real failures
     is ignored far more often than the ones it was
     compared to!

(b) Standards which ensure readability and consistency
     MAY (are there any empirical studies?) prevent
     actual failures by reducing errors in comprehension
     of detail.

After fifteen years of complaining about occasional
deliberate and unjustified violations of standards,
I was horrified to read that some organization had
allegedly adopted an allegedly _good_ standard and
then violated it EVERY OTHER LINE OF CODE !!!!

Re: Case dependence and coding standards

[Georg Bauhaus]

Wesley Groleau <wesgroleau@despammed.com> wrote:
 
:   It is subjective, but I think
: my intuition is influenced by the empirical studies I've read on
: readability and human factors, as well as by the numerous
: misunderstandings I've witnessed people making on poorly formatted
: code and technical prose, not only in software work, but in teaching
: math, language, and electronics, and in reading and writing technical
: material myself.

Could you share your results with us? I think they will add to
the repertoire of people who will make style decisions, and if 
there is sound reasoning behind these decisions, it might increase
the likelihood of of, uhm, common sense.


:> : Notice that I never intended screwing up the comments as your
:> : strawman suggests.
:> 
:> It was not my intention to suggest that you screw up comments.
: 
: But your counterexample was prose such as would only occur
: in comments.  Sorry if I misunderstood your intent.

It might have been an attempt to be a little provocative.
I hope you don't mind. 


-- Georg

Re: Case dependence and coding standards

[Georg Bauhaus]

Stephen Leake <Stephe.Leake@nasa.gov> wrote:
 
: I disagree. I get very frustrated watching programmers who can't type
: with all ten fingers. Take a lesson and see what you gain!
: 
: I don't have numbers, but I bet the time spent typing is about 10% of
: my time on average (some of it in this newsgroup :). If I can cut that
: to 8%, it's worth it.

Phew. That sounds like Benjamin Franklin on keystrokes :-)
http://www.sacklunch.net/poorrichard/Necessary_Hints_to_Those_That_Would_Be_Rich.html

-- Georg
written using ten fingers.

Re: Case dependence and coding standards

[Preben Randhol]

Georg Bauhaus wrote:
> Stephen Leake <Stephe.Leake@nasa.gov> wrote:
>  
>: I disagree. I get very frustrated watching programmers who can't type
>: with all ten fingers. Take a lesson and see what you gain!  : : I
>don't have numbers, but I bet the time spent typing is about 10% of :
>my time on average (some of it in this newsgroup :). If I can cut that
>: to 8%, it's worth it.
> 
> Phew. That sounds like Benjamin Franklin on keystrokes :-)
> http://www.sacklunch.net/poorrichard/Necessary_Hints_to_Those_That_Would_Be_Rich.html

Or : 

   "I [..] am rarely happier then when spending an entire day programming
   my computer to perform automatically a task that it would otherwise
   take me a good ten seconds to do by hand. Ten seconds, I tell myself,
   is ten seconds. Time is valuable and ten seconds' worth of it is well
   worth the investment of a day's happy activity working out a way to
   save it".

   -- Douglas Adams, "Last Chance to See" 

Preben who is currently making a small touch typing program for the
reason stated above ;-)

PS: Touch typing is not so easy when you have to use a lot of
whitespaces IMHO.

-- 
Preben Randhol                    http://www.pvv.org/~randhol/

Re: Case dependence and coding standards

[Wesley Groleau]

> : my intuition is influenced by the empirical studies I've read on
> : readability and human factors, as well as by the numerous

Well, the studies I've read are not right at hand
(stashed away in boxes of paper) but I remember that
one of the books was by Deborah J. Mayhew: Principles
and guidelines in software user interface design
And it did have plenty of citations.  A little old,
but lots of good info in it.

However, one thing about the book bothered me:
Inside both covers were figures with captions
about how the figure illustrated this or that
effective use of color for this or that purpose.
Unfortunately, some idiot at the publishing house
decided to save money by printing them all gray scale!

In teaching and reading, it's hard to be specific,
but things that are suitable for tables should _be_
in tables instead of prose.  It's just easier to take
in the concepts.  This would be almost any sort of
list or repetitive structure.  An if statement is
not repetitive, so nothing is gained by tabular structure.
A case statement, or an if with multiple elsifs, or
a list of declarations is basically a table.

And tables are easier to read if they are really tables.
I understand that source code is affected by other factors
which can make tabular format impractical sometimes.
At those times, a little thought can select the most
readable format.

But, now that I've soapboxed on that a while, let me
freely admit that it's NOT the most important thing
in maintainable code.

Re: Case dependence and coding standards

[Georg Bauhaus]

Wesley Groleau <wesgroleau@despammed.com> wrote:
: 
:> : my intuition is influenced by the empirical studies I've read on
:> : readability and human factors, as well as by the numerous
: 
: Well, the studies I've read are not right at hand
: (stashed away in boxes of paper) but I remember that
: one of the books was by Deborah J. Mayhew: Principles
: and guidelines in software user interface design
: And it did have plenty of citations.  A little old,
: but lots of good info in it.

Thanks. Interesting links from there,
http://www.acm.org/sigs/sigchi/chi97/proceedings/tutorial/djm.htm

: However, one thing about the book bothered me:
: Inside both covers were figures with captions
: about how the figure illustrated this or that
: effective use of color for this or that purpose.
: Unfortunately, some idiot at the publishing house
: decided to save money by printing them all gray scale!

The Chinese, masters of printing, frequently use but
two colors: red and black. Has worked for a long long
time. Just to mention :-)


-- Georg