Re: Coding Standards

[Ken Garlington <garlingtonke@lmtas.lmco.com>]

W. Wesley Groleau (Wes) wrote:

> Now if they are going to
> change it, yes, I will vigorously defend the current coding standards of
> the project.

Do you defent the _current_ coding standards of the project, or the
standards under which the code was originally written? It seems to me that,
if you follow Mr. Duff's approach to coding standards, two things happen:

1. For a long-lived project, you are constrained from changing your coding 
standards over time, since a change in the coding standards may change the 
"meaning" (not necessarily in the strict Ada sense, but in the looser sense 
of information being communicated to the reader) of the existing program.

2. If the code from the existing project is reused in a different project,
then that project is also constrained in what it can have it its coding 
standards. (I have no idea what happens when you reuse code from two sources 
with conflicting meanings. I guess you have to rewrite code from one of the 
sources).

It seems to me that it is not a good idea to have things in coding standards 
that (a) relate to the meaning of the program and (b) are not obvious 
without referring to those standards. So far, I haven't seen any code 
examples that couldn't be readily rewritten to make the meaning obvious - 
"self-sufficient". There may be such examples; I would like to see one 
before I concede this point.

Here's one common coding standard example which I think violates this rule 
(and which I don't like). Many coding standards have a comment in their 
prologue that says:

--  EXCEPTIONS RAISED:

When I see this, I think: Is this just user-defined exceptions, or any 
exception? Does it include exceptions raised by called operations? I think 
that, if a coding standard has such a thing in it, that the comment should
be worded to make this obvious; e.g.

--  USER-DEFINED EXCEPTIONS RAISED LOCALLY:

or the comment should be deleted. I know the usual objection: "It's too 
wordy!" However, (a) if you use a good editor, you don't type this stuff in 
anyway and (b) isn't a few extra words that add to readability a hallmark of 
Ada?

As a side issue, I distrust this part of the prologue when reading code,
since the prologue is not close to the actual code and thus tends to track
the code poorly. When I review code using such a standard, I often find that
this part of the prologue is either wrong when first written, or becomes
wrong through maintenance.  Similarly, if I wanted to communicate how an
algorithm uses a data structure, I would want that information to be closer
to the algorithm than to the data structure.

-- 
LMTAS - "Our Brand Means Quality"