Public Forum Issue/Nitpick

Public Forum Issue/Nitpick

[David Weller]

OK, Here's a gripe (nitpick, if you're of that opinion):
 
At the latest Tri-Ada, the Software Productivity Consortium (SPC),
in cooperation with the AJPO, announced that the book,
"Ada Quality & Style" (AQ&S) was now placed in the public domain
(with appropriate recognition of copyright).  The manual released
publicly is now called the 2.0 version of AQ&S.  The implication
at Tri-Ada '91 was that SPC was now accepting comments from the 
public for suggestions to improve their (near) pending 2.1 version.
Instead of selecting the SEVERAL issues in the book that I take 
exception to, I'd rather discuss the one that I consider the most 
serious (well, ok, let's say, "most debatable"): Case usage.
 
For those of you who HATE this kind of argument, here's a chance to 
'j'unk this article:
\f

OK, for those of you remaining (and I HOPE somebody from SPC is 
still here :-), here's my point:
The AQ&S Guide points out (section 2.1? Don't have it next to me
right now -- pretty good way to let you think this is an "informed"
opinion, huh?) that their recommendation, and the case style followed
throughout the guide, is lower case reserved words and everything
else in UPPER_CASE.  They quickly go on to point out that case usage
is a matter of taste (hence it's debatability), and that individual
organizations should set a style and follow it.  I claim that this
is preposterous, or at the least, unfair.  

In my previous organizations that used Ada (two of 'em , not counting
my current employer), "The Management" decided that the format in the
LRM was sufficient for a coding "standard", and thus employed the
style ENDORSED by SPC (Note carefully the trigger word <--).  In 
neither case did "The Management" evaluate the "why"s as to case
usage.  It was in the LRM, so that was the law.  It was also an
acceptable compromise between their old language (which required
upper case), and the "new" language (which was case sensitive,
which, IMVHO, was infinitely dumber than all upper case).  

My point? (I bet you thought I'd never get there! ;-)  The SPC
style PERPETUATES this cro-magnon decision making process
(personally, I'm in favor of ad hominem arguments, won't you
agree?).  My proposal, and I dare say I have found this to
be a widely accepted approach, is lower case reserved words
and mixed case identifiers.  My justification: ALL UPPER CASE
WORDS _DECREASE_ READING COMPREHENSION, OUR BRAINS HAVE NOT
BEEN TRAINED TO "READ" ALL UPPER CASE WORDS UNLESS YOU'RE
A 30 YEAR COBOL/FORTRAN DINOSAUR!!!  (Please, gentle reader, should 
you be a member of such a long and distinguished career in
the aforementioned languages, do not take offense at the comments,
it was just to make a point that UPPER CASE WORDS LOOK DUMB)
(Also, carefully notice the context switch; I've used upper case,
in accordance with netland rules (sec. 5.1, para. 13), which
states I may use upper case to indicate YELLING!!!).

I'm now interested in hearing rebuttals, "shut-up"s, flames, etc.,
I only ask that is be done in public.  (I"m writing "off-the-cuff"
anyway, I'll apoligize for transgressions later on).

----------------------------------------------------------------
Dave Weller              |  I'm the Ultimate Cultural Masochist:
wellerd@ajpo.sei.cmu.edu |  I speak both Ada AND Esperanto!
----------------------------------------------------------------

Re: Public Forum Issue/Nitpick

[Timothy Harrison]

In article <815@ajpo.sei.cmu.edu> wellerd@ajpo.sei.cmu.edu (David Weller) write
s:
>OK, Here's a gripe (nitpick, if you're of that opinion):
> 
> ...
>The AQ&S Guide points out...
>               that their recommendation, and the case style followed
>throughout the guide, is lower case reserved words and everything
>else in UPPER_CASE.  They quickly go on to point out that case usage
>is a matter of taste (hence it's debatability), and that individual
>organizations should set a style and follow it.  I claim that this
>is preposterous, or at the least, unfair.  
>
>In my previous organizations that used Ada (two of 'em , not counting
>my current employer), "The Management" decided that the format in the
>LRM was sufficient for a coding "standard", and thus employed the
>style ENDORSED by SPC (Note carefully the trigger word <--).  ...
>
>My point? (I bet you thought I'd never get there! ;-)  The SPC
>style PERPETUATES this cro-magnon decision making process
>(personally, I'm in favor of ad hominem arguments, won't you
>agree?).  My proposal, and I dare say I have found this to
>be a widely accepted approach, is lower case reserved words
>and mixed case identifiers.
  [...]

Any style guide must pick a style and consistently use it.  The
upper/lower case conventions of the Ada RM happened to be chosen for
AQ&S.  As stated in AQ&S (p. 5, para 2):

    "If you disagree with the specific recommendations, you may want
     to adopt your own set of conventions which still follow the
     general purpose guidelines.  Above all, be consistent across your
     entire project." 

The specific guideline in AQ&S (p. 18, section 3.1.3) is:

    "Make reserved words and other elements of the program visually
     distinct from each other."

It appears that you disagree with your management's decisions and the
decision of the AQ&S authors regarding a matter of style.  The
arguments for and against particular upper/lower case conventions have
been aired many times in this (and other newsgroups).  The issue
remains an issue with no widespread concensus.  If you want to adopt a
convention different from that recommended in AQ&S, convince your
management.  No matter what recommendation was made in AQ&S there
would be people who like it and those who don't.  Apparently, you
don't.

Let's not get into capitalization flames that go on interminably.
There are many more substantive issues that can be discussed.

-- Tim Harrison <issi!harrison@cs.utexas.edu>
-- International Software Systems Inc.
-- 9430 Research Blvd/Echeleon IV, Suite 250/Austin, TX 78759
-- Phone: (512) 338-5722  FAX: (512) 338-5757

>> Disclaimer: I was a reviewer and contributor to both versions of AQ&S.
-- 
-- Tim Harrison (harrison@software.org)
-- Software Productivity Consortium / 2214 Rock Hill Road / Herndon, VA 22070
-- Phone: (703) 742-7113 / FAX: (703) 742-7200

Re: Public Forum Issue/Nitpick

[swrinde!cs.utexas.edu!hermes.chpc.utexas.edu!corvette.utdallas.edu!ggraha]

I agree that using upper-case is less readable.  I like lower case for reserved
words and mixed case for all other words.  My first Ada job started this
way, and then changed to the LRM style to be consistant with another group
that had already written more code than we had.

My current project is based on a draft MIL-HDBK-1804 Ada Style Guide.  This
is the most detailed coding and style guide I have ever seen.  We are required
to put reserved words and attributes in lower case, type identifiers and
enumeration literals in all caps, and all other identifiers in mixed case.
Although this has the advantage of giving a little more information to the
reader, I still prefer using mixed case for all identifiers.

The last I heard is that MIL-HDBK-1804 did not ever pass beyond its draft
status.

Re: Public Forum Issue/Nitpick

[agate!spool.mu.edu!mips!samsung!uakari.primate.wisc.edu!usenet.coe.montan]

In article <815@ajpo.sei.cmu.edu> wellerd@ajpo.sei.cmu.edu (David Weller) write
s:
 [ stuff deleted ]
>
>OK, for those of you remaining (and I HOPE somebody from SPC is 
>still here :-), here's my point:
>The AQ&S Guide points out (section 2.1? Don't have it next to me
>right now -- pretty good way to let you think this is an "informed"
>opinion, huh?) that their recommendation, and the case style followed
>throughout the guide, is lower case reserved words and everything
>else in UPPER_CASE.  They quickly go on to point out that case usage
>is a matter of taste (hence it's debatability), and that individual
>organizations should set a style and follow it.  I claim that this
>is preposterous, or at the least, unfair.  

I think you mean that their inconsistency is preposterous. I agree. 
Either they're endorsing the LRM style or they're not. AQ&S is a fine
bureaucratic document in that every time they take a stand, they
immediately back away from it. I don't happen to agree with the LRM
style, either.
>
>In my previous organizations that used Ada (two of 'em , not counting
>my current employer), "The Management" decided that the format in the
>LRM was sufficient for a coding "standard", and thus employed the
>style ENDORSED by SPC (Note carefully the trigger word <--).  In 
>neither case did "The Management" evaluate the "why"s as to case
>usage.  It was in the LRM, so that was the law.  It was also an
>acceptable compromise between their old language (which required
>upper case), and the "new" language (which was case sensitive,
>which, IMVHO, was infinitely dumber than all upper case).  

Hmmm. In defense of SPC, they can't be held responsible for managers
who won't put their brains in gear.

 [ stuff deleted ]

>
>          My proposal, and I dare say I have found this to
>be a widely accepted approach, is lower case reserved words
>and mixed case identifiers.  My justification: ALL UPPER CASE
>WORDS _DECREASE_ READING COMPREHENSION, OUR BRAINS HAVE NOT
>BEEN TRAINED TO "READ" ALL UPPER CASE WORDS UNLESS YOU'RE
>A 30 YEAR COBOL/FORTRAN DINOSAUR!!!  (Please, gentle reader, should 

 [ stuff deleted ]

>in accordance with netland rules (sec. 5.1, para. 13), which
>states I may use upper case to indicate YELLING!!!).
>
Yes, I've used this on the net. Too often, in some readers' opinion :-)

Seriously, as a teacher of first-year students, I happen to believe in
the importance of brainwashing them with templates like the usual
control structures. We learn by absorbing patterns, and the "combs"
of control structures are some of these templates. Ergo, I use
UPPER-CASE for reserved words, and mixed case for other stuff.
I am not alone, even in the Ada world; even Norm Cohen did it in his book.

On the other hand, I've had to put on my asbestos suit for the flames
I've gotten from some quarters in the Ada world, for DARING to
deviate from the LRM in my book. Upper-cased reserved words?
HERESY! Burn the infidel!

In freshman-CS-teaching circles, there are 2 religions on this: put
reserved words in lower case to emphasize what comes between them, or
put them in upper case to emphasize them. A student who survives the
first semester is capable of joining whatever religion his subsequent
teachers or managers impose. The reserved-word issue is a minor one,
except in the freshman semester, where we'll fight for our religions
to the very death. Check your Pascal texts for examples of both.

I agree unequivocally that USING UPPER CASE FOR MOST OF THE PROGRAM,
INCLUDING LONG IDENTIFIERS, is jarring, counterintuitive to readers
of English, and therefore a stupid rule to set. Since you were at Tri-Ada,
you might have heard Jan Hext, the Australian who gave one of the
education keynote talks, say that the ALL UPPER CASE convention is also
responsible for getting Ada a lot of bad press among teachers. I agree.

SPC would do well to change their endorsement of the LRM convention 
(WHICH EVEN THE LRM ITSELF ADMITS IS ONLY ONE OF A NUMBER OF
CONVENTIONS) to a set of examples of different styles, admonishing
managers to choose one consistently.

BTW - there is a different style used in Europe, and it's supported
by several prettyprinters. I don't recall the details - does anyone
else out there?

Wishing you all good luck with your case religions, I remain

Mike

Re: Public Forum Issue/Nitpick

[paul goffin]

In article <1991Nov21.222253.1040@milton.u.washington.edu>, mfeldman@milton.u.w
ashington.edu (Michael Feldman) writes:
>  [ stuff deleted ]
> 
> BTW - there is a different style used in Europe, and it's supported
> by several prettyprinters. I don't recall the details - does anyone
> else out there?
> 
> Wishing you all good luck with your case religions, I remain
> 
> Mike

The Upper/Lower question case has been the most controversial issue on every
Ada coding standard meeting that I have attended.  (Perhaps because it is
about such a trivial thing that _everyone_ has an opinion.)

Another good one is file name conventions.  (.Spec, .Proc, .Task, P_Test.ada
                                              S_Test.ada etc.)

The 'European' style is, however:-

lower case for reserved words.
Capitial letters used for the Initial letters of most words in identifiers.

Thus:-

procedure Test is
    Counter : Integer;
    Another_Counter : Integer;
    Long_and_Complex_Name : Float;
       -- opinions vary as to whether or not the 'and' should be 'And'.
begin

    Counter := 1;
    -- etc.
end Test;
 
The Telesoft pretty printer supports this style (-e option).  I think Verdix
does as well.

Paul.

Re: Public Forum Issue/Nitpick

[Beth Walker]

wellerd@ajpo.sei.cmu.edu (David Weller) writes:

> My proposal, and I dare say I have found this to
> be a widely accepted approach, is lower case reserved words
> and mixed case identifiers.

Hear, hear.  I have used PL/M (sort of like PL/1), C and Ada.  The
convention on those projects was the above convention.  The only 
addition we made to that was in the C program, where we specified
that the defined literals were all in upper case, to distinguish
them from variables.  

Writing large amounts of code using all upper case for one group
of words and lower case for another category also slows things
down considerably for those of us that don't have intelligent
text editors which know the language we are writing in (and which
know the conventions we are following).  It's a lot easier, more
intuitive and MUCH more readable to use the First_Letter_Caps
convention.  

Re: Public Forum Issue/Nitpick

[Pat Rogers]

> The Telesoft pretty printer supports this style (-e option).  I think Verdix
> does as well.
> 

Speaking of pretty printers, is there a later version of the Intermetrics
(NOSC) pretty printer than version 1.0?  That release coughs up on record
rep clauses...

Thanks
Pat Rogers
progers@ajpo.sei.cmu.edu