Request for Ada Coding Standards

Request for Ada Coding Standards

[George Haddad]

I have been given the (un)enviable task of trying to put together
coding standards for a project.  Actually, I have been asked to
discover/create a consensus on coding standards which can then be used
as inputs to the _actual_ author(s) of the standard.

   After sitting down my herd of "rugged individualists" with some
copies of the SPC's Ada Quality and Style Guide (AQS), it became
apparent that although some people agree on some issues, there is not
even _one_ guideline with which everyone agrees!

   One "problem" is that the AQS includes "guidelines" which actually
constitute design standards or design advice -- and frequently darn good
advice at that  :-)  -- intermixed with rigid, enforceable coding
_standards_.  (Or generic templates for same, e.g. "There shall be no
more than X characters per physical line of source code.  You pick X.")

   What we would like to try next is to present the "rugged
individualists" with an existing, publicly available standard consisting
as much as possible of only the rigid, enforceable types or requirements
which some other project has found useful and let said individualists
vote "yea" or "nay" on concrete examples.

   SO, to cut to the chase, is there anyone out there willing to send me
(via e-mail or URL) publicly available coding standards from their
(hopefully successful) projects.  I know that Prof. Dewar has said that
ACT has well-defined coding standards for GNAT.  Are those available to
the public without charge, or treated as competitively-valuable
information?  Anyone else?  Thanks in advance.
*****************************************************************
I found these opinions on my doorstep, would you please give them a good
home?

Re: Request for Ada Coding Standards

[Robert Dewar]

George said

<<   SO, to cut to the chase, is there anyone out there willing to send me
(via e-mail or URL) publicly available coding standards from their
(hopefully successful) projects.  I know that Prof. Dewar has said that
ACT has well-defined coding standards for GNAT.  Are those available to
the public without charge, or treated as competitively-valuable
information?  Anyone else?  Thanks in advance.>>

There are two GNAT style rules:

1. Write according to the rules for -gnatg turned on (see style.adb for
full documentation)

2. Write in the same style as the rest of GNAT

The second rule is much harder to document. Parts of it could be documented,
but some of it is related to the feel of how things should look, and is not
so easily documented!

However, it is no secret, and all the information is available to the
public without charge -- just look at the GNAt sources!

Re: Request for Ada Coding Standards

[Michael F Brenner]

Why ask people to standardize syntax instead of the things that
make the code work? Why not ask people to:

   document the preconditions and boundaries of the software
   not delete customer service requests until released
   minimize coupling (such as pointers or references to global variables)
   maximize cohesion (each unit does one thing in a simple manner)

but do it any style they like. They will produce higher quality at
a lower life-cycle cost if you measure the above 4 items instead of
lines of code, capitalization, indentation, number of lines per unit,
bulky unit headers, meaningless comments, complexity metrics that
penalize nested CASE statements, or complexity metrics that give
equal penalty to multiple entrances (BAD) and multiple exits (GOOD),
in my opinion. I am not aware of any research that shows a reduction
of life-cycle cost for measuring syntax compliance over my 4 suggested
standards above. As a matter of fact, I am not aware of any research
that shows a reduction in life-cycle cost for having a syntax standard
over any ONE of my 4 suggested standards above.

Mike Brenner

Re: Request for Ada Coding Standards

[Robert Dewar]

Mike Brenner says

<<Why ask people to standardize syntax instead of the things that
make the code work? Why not ask people to:

   document the preconditions and boundaries of the software
   not delete customer service requests until released
   minimize coupling (such as pointers or references to global variables)
   maximize cohesion (each unit does one thing in a simple manner)

but do it any style they like. They will produce higher quality at
a lower life-cycle cost if you measure the above 4 items instead of
lines of code, capitalization, indentation, number of lines per unit,
bulky unit headers, meaningless comments, complexity metrics that
penalize nested CASE statements, or complexity metrics that give
equal penalty to multiple entrances (BAD) and multiple exits (GOOD),
in my opinion. I am not aware of any research that shows a reduction
of life-cycle cost for measuring syntax compliance over my 4 suggested
standards above. As a matter of fact, I am not aware of any research
that shows a reduction in life-cycle cost for having a syntax standard
over any ONE of my 4 suggested standards above.>>

Actually there *is* research that shows the benefit of uniform style,
at least in a COBOL environment, and it seems pretty clear that these
benefits are language independent.

Yes, we know that Michael does not think that coding standards are
worth while, but this is really such a far out view that I don't think
it is worth discussing (especially since it is unlikely to add anything
over the last time we did). The fact is that the great majority of the
programming community agrees that uniform coding standards are necessary,
so it seems a good idea to concentrate on WHAT standards should be used,
which was indeed the original posters interest, rather than warming over
previous discussions with Michael on WHETHER standards are uself. The
latter discussion is unlikely to add anything new.

On the other hand, I cannot imagine any research which shows that
"not deleting customer service requests until released" helps
code quality, or that "maximizing cohesion" helps code quality.
These ideas, while reasonable in some environments, are far too
vague.

Also I am not even sure that i agree with "each unit does one thing".
The idea of a package of related operations seems natural and desirable
to me, rather than splitting eafch function into a separate package.
\x1adp

Re: Request for Ada Coding Standards

[George Haddad]

Michael F Brenner wrote:
> 
> Why ask people to standardize syntax instead of the things that
> make the code work? Why not ask people to:
[snip]

   We ask people to do lots of things. {Silly and otherwise  :-)  Just
ask anyone associated with DoD procurement of software.}  This
particular request is to facilitate my completing a particular task
involving coding standards.  The assignment for me to complete this task
to the best of my ability is not (regrettably or otherwise) vulnerable
to discussion.  (By which I mean that all the cogent, well-thought-out
arguments in the world as to why coding standards are "the tools of the
devil", will not in any iota of degree convince the fellow doing my
performance appraisal that I didn't really need to complete my assigned
task anyway.  :-))
*****************************************************************
I found these opinions on my doorstep, would you please give them a good
home?

Re: Request for Ada Coding Standards

[George Haddad]

Robert Dewar wrote:
> There are two GNAT style rules:
> 
> 1. Write according to the rules for -gnatg turned on (see style.adb for
> full documentation)
> 
> 2. Write in the same style as the rest of GNAT
> 
> The second rule is much harder to document. Parts of it could be documented,
> but some of it is related to the feel of how things should look, and is not
> so easily documented!

   As far as style.adb, on our site only the GNAT binaries had been
installed, so I'm off to get sources from the ftp site. I expect that
will be no problem.  (But, my expectations are often wildly optimistic. 
:-))

   For rule 2, "hard" (or even "not easy") doesn't mean "impossible". 
Do you have any existing documentation on Rule 2.  I know you have
posted in the past that you, are (or were) the final arbiter of Rule 2,
but has any effort been made to codify Rule 2's criteria?  (Or, does any
succesful attempt to codify a criterion for
Rule 2 automatically get converted into a new part of Rule 1 instead? 
:-))

> However, it is no secret, and all the information is available to the
> public without charge -- just look at the GNAt sources!

   Yes, I know.  I was merely referring, tongue-in-cheek, to your
not-infrequent complaint that many users of GNAT do not read
gnatinfo.txt.  :-)  Thank you for your response.
*****************************************************************
I found these opinions on my doorstep, would you please give them a good
home?

Re: Request for Ada Coding Standards

[Jeff Burns]

George,

If you become interested in checking out tools that help automate compliance
with the SPC AQ&S, please take a look at our products: Ada-ASSURED and
Ada-Utilities.

Ada-ASSURED is a language-sensitive editor that formats code as it is being
typed or read.  Warning messages, shown either as comments in the code or
displayed in a separate window, alert you to style problems.  There are
"indicator" messages that warn you when you are approaching an undesirable
parameter you have defined, e.g. the current structure in which you are
working has 4 nested control structures and your coding standard allows
nesting to only 5 levels (per AQ&S).  "Violation" messages to alert you to
... well ... violations of your coding standard.

Ada-Utilities provides many of the same facilities as Ada-ASSURED.  It's for
sites that don't need an LSE, yet still want to ensure their code complies
with their coding standards.  It's a set of language-sensitive batch tools
designed for analyzing multiple files at once and it produces web
browse-able HTML reports with metrics of coding style standards compliance
along with hypertext cross-referencing to the source code and corresponding
sections of the AQ&S (or your in-house documentation, if desired).

Both Ada-ASSURED and Ada-Utilities can be customized to assist compliance
with the coding standards your group comes up with.  Many of the rules they
monitor may be turned on/off or can be parameterized.  Both tools can
automatically correct some style violations and additional code
transformations can be written with the scripting language that's included.

I've posted additional information in comp.lang.ada before that I think you
can still access through Deja News at:

http://xp6.dejanews.com/getdoc.xp?recnum=13688149&server=db97p2&CONTEXT=8719
98805.1996556705&hitnum=20

Contact me directly if you'd like a complete information package or to
arrange a demo.

-----------------------------
Jeff Burns, Director of Marketing
GrammaTech, Inc.
One Hopkins Place
Ithaca, NY  14850
ph: 607-273-7340
fax: 607-273-8752
e-mail:  jeff@grammatech.com
www:  http://www.grammatech.com
Team Ada
==============================
Ada-ASSURED
    LSE
    Automatic Style Standards Compliance 
    Browser
    QA Tool 
    Code Transformer
"Cure for the Common Code"
============================

"Technology will allow us to be whatever we are already, only more so."

-- Arno Penzias

Re: Request for Ada Coding Standards

[George Haddad]

Jeff Burns wrote:
> If you become interested in checking out tools that help automate compliance
> with the SPC AQ&S, please take a look at our products: Ada-ASSURED and
> Ada-Utilities.

   Thank you.  Automation is an issue which is being dealt with as
well.  However, my focus at the moment is on getting the "rugged
individualists" to agree on _anything_.  Then we can automate some or
all of what they agree on. :-)
*****************************************************************
I found these opinions on my doorstep, would you please give them a good
home?