Coding Standards

Coding Standards

[W. Wesley Groleau (Wes)]

If you haven't been following a recent "wordy" but interesting thread
in comp.lang.ada, one of the participants made a pithy point that's
worth repeating:

"... goal should be coding standards that make it easy to read the code,
not code that makes it necessary to read the coding standards."

Indeed, if you can't understand or maintain the code without the standard,
then the coding standard is not making the code more maintainable, is it?

--
---------------------------------------------------------------------------
W. Wesley Groleau (Wes)                                Office: 219-429-4923
Magnavox - Mail Stop 10-40                               Home: 219-471-7206
Fort Wayne,  IN   46808              elm (Unix): wwgrol@pseserv3.fw.hac.com
---------------------------------------------------------------------------

Re: Coding Standards

[Robert A Duff]

In article <9605151401.AA04364@most>,
W. Wesley Groleau (Wes) <wwgrol@PSESERV3.FW.HAC.COM> wrote:
>Indeed, if you can't understand or maintain the code without the standard,
>then the coding standard is not making the code more maintainable, is it?

By the same argument, why should programmers have to read the Ada
manual?  After all, if you can't understand or maintain the code without
the Standard, then the language standard is not making the code more
readable.  For example, if you don't understand the type checking rules,
then type checking won't help you understand the program.  ;-)

I can assure you that if you work on a project where I'm the boss, and
it's written in Ada, you will be required to know Ada, and to know
project-wide conventions about Ada, and so on.

- Bob

Re: Coding Standards

[Ken Garlington]

W. Wesley Groleau (Wes) wrote:
> 
> If you haven't been following a recent "wordy" but interesting thread
> in comp.lang.ada...

"Wordy," eh? (Everybody has to be a critic.... :)

OK, let me take a crack at summarizing the thread, then. The topic is
on coding standards for objects (including record components, etc.) which
reference other objects. I'm going to call them "pointers," rather than the
Ada term "access," for reasons that will hopefully become obvious later.

Here's some possible goals for such a standard, and some diverging opinions
on how to meet those goals.

A. When an Ada access type is being used for a pointer, it would be useful to
communicate to the maintainer when the default "null" is a useful value for that
object, as opposed to being basically an "undefined" or "uninitialized" value.

APPROACH #1: When null is a useful value for a pointer, explicitly initialize the
pointer to null, as in:

  Thingy : Some_Access_Type := null;

If the maintainer is aware of the coding convention being used, and assuming that
all operations that use this value all work the same way, and that the maintainer
looks at the data structure before passing it to the operation, then it would be
legal to use this object in an algorithm without checking for null first; e.g.

  Do_Something ( With_This => Thingy );

If the explicit null is not given, then some code such as the following might be
needed:

  if Thingy = null then
    -- set the thingy, raise an error, etc.
  else
    Do_Something ( With_This => Thingy );
  end if;

Note that a variation of this approach would declare a value for each appropriate
access type; e.g.

  type Some_Access_Type is access ...;
  No_Particular_Value : constant Some_Access_Type := null; -- indicates "legal" null

  ...

  Thingy : Some_Access_Type := No_Particular_Value;

This variation could make it more clear that the original programmer meant to
initialize the value for some reason other than ignorance about Ada's default
value of null for accesses, particularly if No_Particular_Value is commented.

APPROACH #2: Document each operation's assumptions separately at the point
where the operation is declared; e.g.

  procedure Do_Something
              ( With_This : Some_Access_Type ); -- cannot be null

If the maintainer looks at the operation declaration before using it, then the same
effect as approach #1 should occur. Note that access to the coding standard is not
required to read the code.

B. Write code such that it is easy to change the implementation of a particular pointer 
type from an Ada access type to some other type (e.g., an integer index into a predefined
array). [As a side issue, it could be argued that this is a design standard issue, not a
coding standard issue.]

APPROACH #1. Same as approach #1 for (a) above. Having the explicit initialization
permits the maintainer to find those cases where the (now integer) pointer needs to
be explicitly initialized, assuming the maintainer has access to the coding
standard, etc.

APPROACH #2: Create an abstract data type for Pointers (or a particular type of Pointer). 
By hiding the implementation of the Pointer, it can be changed from an access type to an 
integer, etc. without any changes of the use of Pointer. Of course, the ADT should 
reproduce the operations needed by the program (including default initialization of 
Pointers, and/or the exporting of a No_Particular... value.) The ADT could (and also 
probably should) explicitly document its purpose, so that the maintainer understands why 
an access type was not used directly. Note that, even without the comments, access to the 
coding standards should not be needed to read the code. Note also that, if the Pointer is 
a generic, it could lead to fewer source lines of code required than the type-declaration 
plus constant-declaration required in the approach #1 variant.

C. Permit the code to check, for each access to a particular pointer, whether the value
of the Pointer is No_Particular... or an "uninitialized" value, and to take some action 
if the value is "uninitialized".

APPROACH #1. Same as approach #1 for (a) and (b) above. However, since "null" is
used to mean _both_ values in this approach, this will not work. By default, Ada will
check for any attempts to deference a pointer initialized to null, so there is some
coverage in this area by default.

APPROACH #2: Extend the Pointer ADT described in approach #2 of (b) above. The ADT
could have each pointer contain a default value (probably null, when the pointer
is implemented as an access type) and also export a _different_ No_Paticular... value
(in the case of an access type, some allocated value that is not used; in the case
of an integer, some value that is in range for the integer type, but not a value which
can reference an allocated object). This would allow reliable checking on _any_
access of the pointer, or it could be limited to _dereferences_ of the pointer (as
with Ada's Access_Check). Note that it would be fairly easy to turn such checking
on and off (or modify it), since it would be encapsulated within the ADT.


There was also some discussion about how to detect uninitialized values beyond the
Pointer class, which I won't summarize here.

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[Richard A. O'Keefe]

I liked initialised variables a lot, but I get to see rather more
student code than my nerves can really cope with, and the 300th
time you see

	n: Integer := 1;		int n = 0;
	<two pages>			<three pages>
	while n <= max loop		while (n+1 <= max) {
	    <one page>			    { <one page>
	    n := n+1;			    ++n;
	end loop;			   }

(Yes, the C is strangely indented, that's what I see.)
you realise "it is important to group related things together",
and "being able to move the first assignment up into the declarative
region tempts many beginners to do it when they shouldn't".

I've been looking for some guidelines, and I think that these are good:

    - constants MUST be initialised where they are declared

	X: constant Integer := ....;
	int const X = ...;

	(of course this doesn't apply to Ada deferred constants; give me
	credit for some sense.)

    - ALL variables must be initialised before they are used,
	WHETHER THE LANGUAGE WILL INITIALISE THEM OR NOT.

	This means I don't _care_ what Ada initialises pointers to,
	and I don't care what C initialises top-level variables to
	either.

    - other things being equal, the initialisation of a variable
      should be as late as possible.

    - other things being equal, the initialisation of a variable
      should be as close to its uses in the text as possible,
      so that when looking at the uses, the initialisation is
      visible.

I understand why Ada initialises pointers to null, and I wouldn't want
that changed, but if I want to check that a variable is properly
initialised, I want to _see_ an initialisation.

I would also like to point out that in this year's C class, the second
biggest cause of run-time errors (after the obvious biggie: design errors)
was uninitialised variables.  The lucky students were the ones where this
resulted in a NULL pointers that were caught by the hardware.
Students keep on telling me their program "works" when they really mean
that Turbo C failed to notice the problem most of the time.  (They are
actually required to compile their programs on a SPARC/Solaris system,
which is when they start complaining that 'cc' or 'gcc' is "broken".)

For teaching purposes, at any rate, I am 
 *for* any tool that will help to detect uninitialised variable use
 *against* any "solution" to the problem that requires programmer
     intervention; if the students were savvy enough to use such a
     solution, they wouldn't need it so much.

For developing large long-lived software systems where performance is
an issue, the tradeoffs are different.
-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Coding Standards

[Ken Garlington]

Richard A. O'Keefe wrote:
> 
>     - ALL variables must be initialised before they are used,
>         WHETHER THE LANGUAGE WILL INITIALISE THEM OR NOT.
> 
>         This means I don't _care_ what Ada initialises pointers to,
>         and I don't care what C initialises top-level variables to
>         either. ...

> I understand why Ada initialises pointers to null, and I wouldn't want
> that changed, but if I want to check that a variable is properly
> initialised, I want to _see_ an initialisation.

Is this because you don't trust the compiler to obey the language rules in
this area, or some other reason?

Furthermore, what about cases like:

(1)  type Some_Thingy_Type is record
      Some_Component : Integer := 0;
     end record;

     Foo : Some_Thingy_Type; -- or should I explicitly initialize it?

(2)  type Name_Type is String(1 .. 10);

     Blank_Name : constant Name_Type := (others => ' '); -- is "others" too implicit?

> For teaching purposes, at any rate, I am
>  *for* any tool that will help to detect uninitialised variable use
>  *against* any "solution" to the problem that requires programmer
>      intervention; if the students were savvy enough to use such a
>      solution, they wouldn't need it so much.

This is certainly useful; do you see your coding standard as a "tool" in this
context, or are you saying that you would like analysis tools and language
features (e.g. Normalize_Scalars, 'Valid) as "tools"?

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[W. Wesley Groleau (Wes)]

After I said:
>> Indeed, if you can't understand or maintain the code without the standard,
>> then the coding standard is not making the code more maintainable, is it?

R.D. answered:
> By the same argument, why should programmers have to read the Ada
> manual?  After all, if you can't understand or maintain the code without
> the Standard, then the language standard is not making the code more
> readable.  For example, if you don't understand the type checking rules,
> then type checking won't help you understand the program.  ;-)
>
> I can assure you that if you work on a project where I'm the boss, and
> it's written in Ada, you will be required to know Ada, and to know
> project-wide conventions about Ada, and so on.

I think you're reading too much into my comment.  I was not criticizing
your initialization convention (I'm still undecided on that).  Nor did
I suggest that programmers be allowed to shrug off coding standards.
(People that have worked with me know I can be a bit of a curmudgeon
about format and style.)

But the main point of coding standards is maintainability via readability.
I believe that the code should be as clear as possible to the READER without
external support.  There is a difference between a feature of the language
that supports reliability in general and a local convention that adds
semantics to the code.

Readability was one of the original goals of Ada.  If we really wanted to
make sure that people used the standards and references extensively, we
could have derived Ada from RPG, APL, and C rather than Algol and Pascal. :-)

I want the customer, outside consultants, future maintainers, etc.--who may
not be able to find (or who may not be obligated to) a coding standard that
may no longer be valid--to understand the code.  Now if they are going to
change it, yes, I will vigorously defend the current coding standards of
the project.

---------------------------------------------------------------------------
W. Wesley Groleau (Wes)                                Office: 219-429-4923
Senior Software Engineer - AFATDS                         FAX: 219-429-5194
Magnavox - Mail Stop 10-40                               Home: 219-471-7206
1010 Production Road                QuickMail (Mac): wwgrol@most.fw.hac.com
Fort Wayne,  IN   46808              elm (Unix): wwgrol@pseserv3.fw.hac.com
---------------------------------------------------------------------------

Re: Coding Standards

[Richard A. O'Keefe]

I wrote:
 I understand why Ada initialises pointers to null, and I wouldn't want
 that changed, but if I want to check that a variable is properly
 initialised, I want to _see_ an initialisation.

Ken Garlington <garlingtonke@lmtas.lmco.com> writes:

>Is this because you don't trust the compiler to obey the language rules in
>this area, or some other reason?

It's because I want to _see_ the initialisation.
It's not the _compiler_ I don't trust (although, as it happens, I don't
trust my compiler; it's GNAT, and from time to time our technical support
people do something that makes 'gcc -c foo.adb' completely stop working;
software _as shipped_ != software _as installed_).
It's _me_ I don't trust.

I am a bear of very little brain.
I have worked with _lots_ of languages, and continue to use several.
The policy I described (initialise constants in declarations, initialise
variables as close as reasonable to first use) is one that
 - makes sense in _every_ language I use
 - makes sense _whatever_ the data type of a variable is.

If we take "abstract data types" and "uniform reference" at all
seriously, and in Ada I thought we were supposed to, I _should_ be
using a convention for initialisation which doesn't force me to
rewrite the code if I switch from array indices to pointers or vice versa.
Somebody reading my code (probably me) shouldn't have to look up the
type declaration (which may be in some other package entirely) to find
out that what _looks_ like an uninitialised variable is actually ok.

>Furthermore, what about cases like:

>(1)  type Some_Thingy_Type is record
>      Some_Component : Integer := 0;
>     end record;

>     Foo : Some_Thingy_Type; -- or should I explicitly initialize it?

The rule I use is type independent.  It's not the ":= 0" in the
type declaration I mind; it's that I don't like relying on it, not
because the compiler will get it wrong, but because I will.

I actually prefer

	type Some_Thingy_Type is record
	    Some_Component: Integer;
	end record;

	Default_Thingy_Type: constant Some_Thingy_Type :=
	    (Some_Component => 0);

	Foo: Some_Thingy_Type;
    begin
	...
	Foo := Default_Thingy_Type;

If there is a "normal" initial value for a type, I WANT A NAME FOR THAT VALUE!

>(2)  type Name_Type is String(1 .. 10);

>     Blank_Name : constant Name_Type := (others => ' ');
>	 -- is "others" too implicit?

No, of course not.  My rule was about initialising variables.  I said
nothing about "implicit".



>> For teaching purposes, at any rate, I am
>>  *for* any tool that will help to detect uninitialised variable use
>>  *against* any "solution" to the problem that requires programmer
>>      intervention; if the students were savvy enough to use such a
>>      solution, they wouldn't need it so much.

>This is certainly useful; do you see your coding standard as a "tool" in this
>context, or are you saying that you would like analysis tools and language
>features (e.g. Normalize_Scalars, 'Valid) as "tools"?

'Valid is exactly the kind of thing I am _against_ in this context because
it requires explicit programmer intervention.  I am not saying it should
not be in the language.  I am just saying that *as a tool for helping
STUDENTS* it is inadequate (and it wasn't designed for that).  The convention
I mention is a tool for _avoiding_ initialisation errors, not a tool for
checking them.

What I want is static checkers (at _least_ as good as Lint or GCC checking
for uninitialised variables, ideally a lot better because they are pretty
weak) AND DYNAMIC CHECKERS.  Yes, this is the old idea of a "checkout
compiler" as opposed to an "optimising compiler".  Yes, this is the kind
of thing CodeCenter buys you for C.  It has been a while since I used
CodeCenter, but I remember vividly how very efficient a _debugging_ tool
it was.  Code didn't _run_ fast, but it certainly _found mistakes_ fast.

And of course I want them free, yesterday.  Our wonderful new Federal
Government made election promises about maintaining funding for education
and the 2000 Olympics.  Well, the Olympics are safe, but they are now,
only a couple of months after the election, talking about 10% education
cuts.  How this is supposed to make the education system "more competetive"
escapes me; I believe politicians must be on drugs.

-- 
Fifty years of programming language research, and we end up with C++ ???
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

Re: Coding Standards

[Ken Garlington]

Richard A. O'Keefe wrote:
> 
> I am a bear of very little brain.
> I have worked with _lots_ of languages, and continue to use several.
> The policy I described (initialise constants in declarations, initialise
> variables as close as reasonable to first use) is one that
>  - makes sense in _every_ language I use
>  - makes sense _whatever_ the data type of a variable is.
> 
> If we take "abstract data types" and "uniform reference" at all
> seriously, and in Ada I thought we were supposed to, I _should_ be
> using a convention for initialisation which doesn't force me to
> rewrite the code if I switch from array indices to pointers or vice versa.

Two comments:

(1) If you really use an ADT for a pointer, you don't have to rewrite anything
other than the implementation of the ADT to switch between array indices and
pointers. (I showed an example of such an ADT in an earlier thread.)

(2) It seems to me that your approach prohibits certain behavior within an
ADT. In particular, if you want to assure that any object declared with the
ADT has an initial value, it seems like your coding convention would not allow
this. As a result, you must depend upon the user of the ADT to consistently provide
an initial value on the declaration. If they forget, the assumptions of the ADT may 
be broken, or the program may behave erroneously. I would think this would weaken, 
not strengthen, the use of an ADT. It also seems to violate the Ada concept of not
explicitly copying information that can be defined in one place.

> Somebody reading my code (probably me) shouldn't have to look up the
> type declaration (which may be in some other package entirely) to find
> out that what _looks_ like an uninitialised variable is actually ok.

Wouldn't they have to look up the type declaration (or the ADT declaration,
or the algorithm declaration) to determine other information, such as whether the
initial value that _was_ provided was OK, in any case?

> >Furthermore, what about cases like:
> 
> >(1)  type Some_Thingy_Type is record
> >      Some_Component : Integer := 0;
> >     end record;
> 
> >     Foo : Some_Thingy_Type; -- or should I explicitly initialize it?
> 
> The rule I use is type independent.  It's not the ":= 0" in the
> type declaration I mind; it's that I don't like relying on it, not
> because the compiler will get it wrong, but because I will.

However, if all Some_Thingy_Types are supposed to be initially zero (as opposed to
"initialized to some integer value"), isn't it more likely that the coder
will "get it wrong" if the initialization has to be physically repeated for
each declaration?

> I actually prefer
> 
>         type Some_Thingy_Type is record
>             Some_Component: Integer;
>         end record;
> 
>         Default_Thingy_Type: constant Some_Thingy_Type :=
>             (Some_Component => 0);
> 
>         Foo: Some_Thingy_Type;
>     begin
>         ...
>         Foo := Default_Thingy_Type;

I think this may be OK for one Some_Thingy_Type; I wonder about its utility
for multiple Some_Thingy_Type objects that are all supposed to have the same
(or a related; e.g. sequentially increasing) initial value.

> If there is a "normal" initial value for a type, I WANT A NAME FOR THAT VALUE!

I don't see any problem with exporting the default value by name from an ADT,
for example, to use it in a comparison statement. However, you can have a name
without explicitly requiring its use on all declarations. For example:

  package Doctor is

    type Object is ...;
    type Reference is private; -- has initial value of Illegal_Reference.

    function Illegal_Reference return Reference;

    ...

  private

    type Reference is access Object; -- can change to an integer if desired
                                     -- causes all References to be null.

  end Doctor;

  package body Doctor is

    function Illegal_Reference return Reference is begin return null; end;
      -- returns some integer value if Reference changed.

  end Doctor;

This ADT could still be used with your coding style, as follows:

  Some_Doctor : Doctor.Reference := Illegal_Reference;

However, the initial value would be unnecessary. Note that the ADT assumptions
would still be valid if you left the initial value off. However, anyone reading
your code who was not familiar with your coding convention would be confused,
either (a) because you were double-initializing Some_Doctor and/or (b) because
some Doctors were initialized, others weren't.

> What I want is static checkers (at _least_ as good as Lint or GCC checking
> for uninitialised variables, ideally a lot better because they are pretty
> weak) AND DYNAMIC CHECKERS.  Yes, this is the old idea of a "checkout
> compiler" as opposed to an "optimising compiler".  Yes, this is the kind
> of thing CodeCenter buys you for C.  It has been a while since I used
> CodeCenter, but I remember vividly how very efficient a _debugging_ tool
> it was.  Code didn't _run_ fast, but it certainly _found mistakes_ fast.
> 
> And of course I want them free, yesterday.

Well, except for the "free" part, there are certainly analysis tools of this
type available for Ada. Some of them might be discounted (if not free) for
academia; I don't know.

> --
> Fifty years of programming language research, and we end up with C++ ???
> Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[Ken Garlington]

Robert A Duff wrote:
> 
> By the same argument, why should programmers have to read the Ada
> manual?

Funny you should mention this. 

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[Ken Garlington]

Robert A Duff wrote:
> 
> By the same argument, why should programmers have to read the Ada
> manual?  After all, if you can't understand or maintain the code without
> the Standard, then the language standard is not making the code more
> readable.  For example, if you don't understand the type checking rules,
> then type checking won't help you understand the program.  ;-)

(Oops - let's try that again...)

Funny you should mention this. We have a lot of non-programmers that read
(but do not modify) our Ada code. These folks include hardware engineers,
test engineers, etc. who need to understand a particular detail about
an algorithm. They rarely have to resort to an Ada manual to
understand a type definition. This is the wonderful thing about Ada: It's
fairly intuitive to read. Or at least, it should be. I gather you feel
differently. Certainly, I would expect someone _modifying_ the code to be 
familiar with how the language works, which they could get from the ARM.
However, I've often reused code successfully without any knowledge of the
original coding standards.

It also seems to me that your argument regarding the language manual is also
deficient, in that it assumes that if requring knowledge from one source is
necessary, that requiring knowledge from two sources is better. If that's the
case, why not use obscure sequences of letters for all declarations, with a 
third document definining what these sequences actually mean?  Generally, I
would think the _less_ complicated you make the process of understanding and
maintaining software, the better.

> I can assure you that if you work on a project where I'm the boss, and
> it's written in Ada, you will be required to know Ada, and to know
> project-wide conventions about Ada, and so on.

This still begs the question I've asked on a couple of occasions: What
happens when your code is used on my project? If I reuse your code, am
I forced to use your coding standards, in order to keep the code maintainable?
This would seem to be a significant deterrent to its reuse.

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[Robert A Duff]

In article <31AABC53.1080@lmtas.lmco.com>,
Ken Garlington  <garlingtonke@lmtas.lmco.com> wrote:
>Funny you should mention this. We have a lot of non-programmers that read
>(but do not modify) our Ada code.

That probably explains our differences of opinion.  I have never been in
a situation where it was important for non-programmers to understand
code -- if non-programmers need to understand something, I've always had
to write it in plain English.  In *my* experience, the only reason for
somebody to understand code is because that person is a *programmer* who
wants to modify it, debug it, interface to it, test it, etc.  And, of
all those, the most important is "modify", because that's where the most
damage can be done by misunderstanding something.  I certainly don't
claim my experience is universal, of course.

>... These folks include hardware engineers,
>test engineers, etc. who need to understand a particular detail about
>an algorithm. They rarely have to resort to an Ada manual to
>understand a type definition. This is the wonderful thing about Ada: It's
>fairly intuitive to read. Or at least, it should be. I gather you feel
>differently. ...

Well, it depends how far you go in that claim.  Certainly Ada is more
readable to non-programmers than some other languages, and I suppose
that's mildly nice in *your* situation (though irrelevant in mine).
However, if you grab a random person walking down the street, that
person can understand a Robert Ludlum novel and today's newspaper, but
certainly cannot understand a computer program, in Ada or anything else.
But that's OK.  I might not understand *that* person's job, either.

>It also seems to me that your argument regarding the language manual is also
>deficient, in that it assumes that if requring knowledge from one source is
>necessary, that requiring knowledge from two sources is better. If that's the
>case, why not use obscure sequences of letters for all declarations, with a 
>third document definining what these sequences actually mean?  Generally, I
>would think the _less_ complicated you make the process of understanding and
>maintaining software, the better.

OK, I call a truce in the effort to push each other's arguments to
logical extremes.  ;-)

>This still begs the question I've asked on a couple of occasions: What
>happens when your code is used on my project? If I reuse your code, am
>I forced to use your coding standards, in order to keep the code maintainable?
>This would seem to be a significant deterrent to its reuse.

I thought that (repeated) question was rhetorical.  My only answer is,
"Yes, it's hard to interface project A to project B when the coding
standards are incompatible."  Maybe that's one of the (many?) reasons
why Software Reuse hasn't really happened (at least, not to a great
enough extent to solve all the world's software problems).  ;-)

Maybe if we all *agreed* on coding standards, software reuse would be
easier.  The industry is not mature enough for that, unfortunately.
(We can't even all agree on a single programming language, not even
within a single application area!)

- Bob

Re: Coding Standards

[Ken Garlington]

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"

Re: Coding Standards

[Ken Garlington]

Robert A Duff wrote:
> 
> >It also seems to me that your argument regarding the language manual is also
> >deficient, in that it assumes that if requring knowledge from one source is
> >necessary, that requiring knowledge from two sources is better. If that's the
> >case, why not use obscure sequences of letters for all declarations, with a
> >third document definining what these sequences actually mean?  Generally, I
> >would think the _less_ complicated you make the process of understanding and
> >maintaining software, the better.
> 
> OK, I call a truce in the effort to push each other's arguments to
> logical extremes.  ;-)

I don't think you understand. The _core_ of my argument is that the code should
be as self-explanatory as practical, to enhance (a) readability, (b) 
maintainability, and (c) reusability. I accept that there are limits to this goal; 
for example, that knowledge of the Ada standard is still required. In addition, 
for certain kinds of maintenance (major changes in architecture, for example), 
knowledge of the system requirements, etc. are also necessary. However, I'm still 
looking for a case where knowledge of the coding standard used during development 
is legitimately critical to long-term maintenace of the software. Without such
a case, I don't see an obstacle to effective maintenance of code without
reference to the original coding standard.

> >This still begs the question I've asked on a couple of occasions: What
> >happens when your code is used on my project? If I reuse your code, am
> >I forced to use your coding standards, in order to keep the code maintainable?
> >This would seem to be a significant deterrent to its reuse.
> 
> I thought that (repeated) question was rhetorical.  My only answer is,
> "Yes, it's hard to interface project A to project B when the coding
> standards are incompatible."  Maybe that's one of the (many?) reasons
> why Software Reuse hasn't really happened (at least, not to a great
> enough extent to solve all the world's software problems).  ;-)

If the way we use coding standards inhibits reuse, then maybe it's worth
looking at changing the way we write coding standards. Read on...

> Maybe if we all *agreed* on coding standards, software reuse would be
> easier.  The industry is not mature enough for that, unfortunately.
> (We can't even all agree on a single programming language, not even
> within a single application area!)

I still believe there is an alternative to requiring all projects to use a
common coding standard. That alternative is to write the coding standard in
such a way that it is not _required_ for maintenance. Again, the coding standard
should be designed to make the code self-explanatory. Without a coding standard,
there's no guarantee that this will happen. With a "good" coding standard, I think
the code can be read, maintained, and reused without knowledge of the standard.
This may sound paradoxical, but it makes sense to me.

An imperfect analogy: Suppose I reuse Ada 83 code on an Ada 95 project. I would 
hope that the coding standard for the Ada 83 code included provisions to avoid Ada 
95 incompatibilities. However, I should be able to maintain that Ada 83 code with 
my Ada 95 coding standard, without including a section on avoiding Ada 95 
incompatibilities.

Also, as I mentioned before, I think requiring knowledge of the coding standard to
understand the code has consequences beyond reuse. I think it also limits the
ability of the project to evolve the coding standard. Suppose, for example, the
project upgrades to an Ada 95 compiler. That project will probably want to upgrade 
their coding standard. However, if the coding standard has within it the meaning 
of certain non-obvious conventions, the project has to be very careful not to 
change anything in the standard that will invalidate those conventions. On the 
other hand, if the coding standard is not needed to understand the code, this 
should not be as serious a concern.

> 
> - Bob

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[W. Wesley Groleau (Wes)]

I (Wes) wrote:

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

Ken Garlington then asked:

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

The CURRENT standards.  In maintaining and/or re-using code, I have two
rules:

1. If it ain't broke, don't fix it.

2. If it ain't easy to understand, it's broke.

The hard part is defining "easy"  :-)  Most people only want to go by rule #1;
a few of us (myself included) have to be restrained from applying rule # 2 to
90 per cent of existing code!  :-)

>[valid objections skipped]

Those objections are why I agree with you that

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

Bob Duff asked why expecting code readers to know the coding standard was
different from expecting them to know the LRM.  To which I (not very clearly)
stated I want READERS to not need ANY outside source--not even the LRM.
But WRITERS had better know the LRM, the local standards, accepted practice,
and much more.

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

I'll spare you folks my strong opinions on unnecessary duplication.
--
---------------------------------------------------------------------------
W. Wesley Groleau (Wes)                                Office: 219-429-4923
Magnavox - Mail Stop 10-40                               Home: 219-471-7206
Fort Wayne,  IN   46808              elm (Unix): wwgrol@pseserv3.fw.hac.com
---------------------------------------------------------------------------

Re: Coding Standards

[Robert A Duff]

In article <9605291821.AA10842@most>,
W. Wesley Groleau (Wes) <wwgrol@PSESERV3.FW.HAC.COM> wrote:
>Bob Duff asked why expecting code readers to know the coding standard was
>different from expecting them to know the LRM.  To which I (not very clearly)
>stated I want READERS to not need ANY outside source--not even the LRM.

Are you telling me that any random person can understand your Ada code?
Somebody who's profession is "french fry cook at McDonald's", or
"quantum physicist", or "Shakesperian Play critic"?  I skept.  No matter
how intelligent they are, if they don't know *something* about Ada, or
at least programming in general, they're not going to understand
programs written in Ada, IMHO.

>But WRITERS had better know the LRM, the local standards, accepted practice,
>and much more.

Here, we agree.

What I don't understand is why we care so much about the READERS.  Only
the WRITERS can do damage.  If the quantum physicist says, "yeah, makes
sense", then how would we ever know if he was wrong, and why would we we
ever care, if we never let him edit the code?

- Bob

Re: Coding Standards

[Ken Garlington]

W. Wesley Groleau (Wes) wrote:

> Bob Duff asked why expecting code readers to know the coding standard was
> different from expecting them to know the LRM.  To which I (not very clearly)
> stated I want READERS to not need ANY outside source--not even the LRM.
> But WRITERS had better know the LRM, the local standards, accepted practice,
> and much more.

I think the difference in your approach and Bob Duff's approach is that you
expect writers to know the coding standards in the _current_ environment.
Mr. Duff expects writers to know both the _current_ standards, _and_ the standards
under which the code was written. It sounds like, in Mr. Duff's environment,
there is no code reuse and no standards evolution, so that the current standards
_are_ the original standards. Therefore, it's a moot point for him. However, in
the general case, I would not depend on them being the same.

-- 
LMTAS - "Our Brand Means Quality"

Re: Coding Standards

[Frank Manning]

In article <Ds4yqn.667@world.std.com> bobduff@world.std.com (Robert A Duff)
wrote:

> In article <31AABC53.1080@lmtas.lmco.com>,
> Ken Garlington  <garlingtonke@lmtas.lmco.com> wrote:
>> Funny you should mention this. We have a lot of non-programmers that read
>> (but do not modify) our Ada code.
>
> That probably explains our differences of opinion.  I have never been in
> a situation where it was important for non-programmers to understand
> code -- if non-programmers need to understand something, I've always had
> to write it in plain English.  
>    [...]

I can sympathize with both positions. On one hand, non-programmers might
benefit by getting a look under the hood (er, bonnet?). On the other hand,
they would also benefit from a translation to plain English.

This reminds me of a tongue-in-cheek article I posted in September '94
where I had ideas on selling Ada to management, if you're unfortunate
enough to have management populated by control freaks. These are the guys
who, if they know any programming at all, tend to be in love with
QuickBASIC. The idea was you can point out how much easier it is to read
Ada compared to C/C++, and you can appeal to their suspicions that
programming jargon was invented by hackers to exclude everybody else
from the True Brotherhood. I also wrote:

  "We might find allies in coworkers who are non-programmers. They
   already know how dependent their project is on the success of the
   software. They also know how important communication is. Ask them
   if they would like to be able to at least read the source code if
   they wanted to. Show them the two pages of Ada and C code.

  "Ask them if they really want workers to be divided into two
   classes -- the cognoscenti, who are the only ones who can even
   come close to reading the 'code,' and the rest of us. Ada can be
   at least vaguely readable by a non-programmer. C/C++ is
   completely opaque to a non-programmer."

When I wrote this, I was more negative toward C than I am today. I kind
of like the language now, although I like Ada more.

Anyway, the point is that communication is important whenever you have
groups of people trying to work together. Anything that gets in the way
of communication should generally be avoided. Unless you want to end up
like Dilbert.

-- Frank Manning

Re: Coding Standards

[W. Wesley Groleau x4923]

Here we have what at first glance might appear to be a mixture of
"absolute rules" and "merely advice" but in reality the difference
is how hard it is to get a deviation approved.  Even in cases where
no one ever disapproves, the "merely advice" may be valuable for
educating the inexperienced.

The task that is apparently facing William Dale can best be solved
with a single absolute rule:  Code that will not compile is not
acceptable.