Re: Bad coding standards - aesthetics are irrelevant

Re: Bad coding standards - aesthetics are irrelevant

[Singlespeeder]

Much of the debate on aesthetics would be needless if there was a good
freely available non-proprietary tool for reformatting the code, much like
the C world has 'indent'.

Then all you do is specify a company wide set of flags for the tool and
insist that all code is run through the tool with those flags before
checking it into the code libraries.

This is not a new idea - check out 'Code Complete' by Steve McConnell for
more debate on layout backed up by hard figures.

Unfortunately bad coding style is more than mere aesthetics.

As for markers in the code - surely the language standard itself need not
specify them. Neither is there any reason why you or your company couldn't
adopt html (or even xml) in your source code comments and then run the
source through a tool similar to javadoc. Except you'd have to write the
tool. None proprietary please.

Nick Wallis

Re: Bad coding standards - aesthetics are irrelevant

[Larry Kilgallen]

In article <LPBBLLGPHODFBNGLFGJDMELNCBAA.singlespeeder@btinternet.com>, "Singlespeeder" <singlespeeder@btinternet.com> writes:

> As for markers in the code - surely the language standard itself need not
> specify them. Neither is there any reason why you or your company couldn't
> adopt html (or even xml) in your source code comments and then run the
> source through a tool similar to javadoc. Except you'd have to write the
> tool. None proprietary please.

Your request that privately funded tools to meet a private need be released
to the world is unlikely to get sympathy at some sites.

RE: Bad coding standards - aesthetics are irrelevant

[Robert C. Leif, Ph.D.]

From: Bob Leif
To: Singlespeeder et al.

A direct way to enforce an institutional style would be to build automated
tools that reformat the Ada source to beautiful Ada source. For instance, if
an XML schema were created for Ada, it appears to me that it would be
possible to create an ASIS based tool to produce Ada source in XML syntax.
It should then be possible, if need be, to enhance an XML editor to serve as
an Ada programming editor. Since the formatting of XML is separate from the
XML document, it should be possible to create an institutional style sheet.
This technology could be augmented by other ASIS tools which, for instance,
could selectively eliminate Use Package statements and instead perform
renames according to a standard algorithm.


-----Original Message-----
From: comp.lang.ada-admin@ada.eu.org
[mailto:comp.lang.ada-admin@ada.eu.org]On Behalf Of Singlespeeder
Sent: Wednesday, December 20, 2000 2:23 PM
To: comp.lang.ada@ada.eu.org
Subject: Re: Bad coding standards - aesthetics are irrelevant


Much of the debate on aesthetics would be needless if there was a good
freely available non-proprietary tool for reformatting the code, much like
the C world has 'indent'.

Then all you do is specify a company wide set of flags for the tool and
insist that all code is run through the tool with those flags before
checking it into the code libraries.

This is not a new idea - check out 'Code Complete' by Steve McConnell for
more debate on layout backed up by hard figures.

Unfortunately bad coding style is more than mere aesthetics.

As for markers in the code - surely the language standard itself need not
specify them. Neither is there any reason why you or your company couldn't
adopt html (or even xml) in your source code comments and then run the
source through a tool similar to javadoc. Except you'd have to write the
tool. None proprietary please.

Nick Wallis

RE: Bad coding standards - aesthetics are irrelevant

[Robert Dewar]

In article <NBBBJNOMKDIAJALCEFIJGEFJEBAA.rleif@rleif.com>,
  comp.lang.ada@ada.eu.org wrote:
> From: Bob Leif
> To: Singlespeeder et al.
>
> A direct way to enforce an institutional style would be to
> build automated tools that reformat the Ada source to
> beautiful Ada source.


It is no more possible to automate the creation of beautiful
Ada source from junk than it is to automate getting fine art
from photographs. You can do a crude approximation, but beauty
will escape you.

A common coding style goes well beyond what can be enforced by
tools, it really requires everyone to internalize the general
style at all sorts of levels. Just for one example, the use of
comments is something that needs to be standardized. A tool can
make sure the -- is in the right column, but cannot ensure that
the comment is at the right level of semantic abstraction.

In the GNAT project, we have a set of coding standards, and
many of the simple items are enforced (see the -gnaty switch
in GNAT) automatically when we compile. But the level of
uniformity goes far beyond that. The way we work is that when
someone first comes to the project, their code is carefully
reformatted for correct style (by a human, often me :-) and
they learn the style from watching these corrections. If you
look at the revision histories, a very large percentage says
something like "minor reformatting".

I don't think it works even at the simple syntactic level to
use a tool to *convert* code to a common style, as opposed to
*enforcing* the style.

If I am a programmer who absolutely insists on using UPPER_CASE
names, yes, then I can automatically format to mixed case (well
even that's a little tricky and requires exception
dictionaries), but it can be done. The problem is that I will
not like the result. Yes, for my own code, I can keep a local
copy of the NICE_LOOKING_CODE, but what about other people's
code? Unless there are tools to go from the common style to
each person's idiosyncratic style, you will still get what I
call "style lockout", meaning that people do not like to touch
code they find ugly.

It really is much simpler, and quite practical, to get the
whole team using a common style in the first place.



Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Stephen Leake]

"Singlespeeder" <singlespeeder@btinternet.com> writes:

> Much of the debate on aesthetics would be needless if there was a good
> freely available non-proprietary tool for reformatting the code, much like
> the C world has 'indent'.

There is. It's called ada-mode for Emacs. Combined with the equally
free gnat style checker, it's a great tool.

What more do you want?

> Then all you do is specify a company wide set of flags for the tool
> and insist that all code is run through the tool with those flags
> before checking it into the code libraries.

Exactly what our Ada style guide says:
http://fsw.gsfc.nasa.gov/library/standards.html
 
-- 
-- Stephe

Re: Bad coding standards - aesthetics are irrelevant

[William Starner]

Stephen Leake wrote:
> 
> "Singlespeeder" <singlespeeder@btinternet.com> writes:
> 
> > Much of the debate on aesthetics would be needless if there was a good
> > freely available non-proprietary tool for reformatting the code, much like
> > the C world has 'indent'.
> 
> There is. It's called ada-mode for Emacs. Combined with the equally
> free gnat style checker, it's a great tool.
> 
> What more do you want?

Something that works quickly? I use ada-mode, and have that if you want to
indent a large array initalizer, or something in the area of the large array
initalizer, it can get as slow as 3 seconds a line, which in the case of a 100
line array initalizer is terribly slow.

-- 
David Starner - dvdeug@hushmail.com (dstarner98@aasaa.ofe.org off vacation)

Re: Bad coding standards - aesthetics are irrelevant

[Florian Weimer]

William Starner <billeug@worldnet.att.net> writes:

> Something that works quickly? I use ada-mode, and have that if you
> want to indent a large array initalizer, or something in the area of
> the large array initalizer, it can get as slow as 3 seconds a line,
> which in the case of a 100 line array initalizer is terribly slow.

Have you byte-compiled the Lisp files?

Re: Bad coding standards - aesthetics are irrelevant

[Marin David Condic]

Singlespeeder wrote:

> Much of the debate on aesthetics would be needless if there was a good
> freely available non-proprietary tool for reformatting the code, much like
> the C world has 'indent'.

Not everything about style - including asthetics - can be resolved effectively
by a machine. For example, you might have an identifier: Rotor_RPM. Automatic
case rules would have a hard time noting that RPM is an abbreviation and
should be upper case. Or it could just preserve case as it was given, but then
what stops someone from writing rotor_rpm which might violate the coding
conventions?

>
> Unfortunately bad coding style is more than mere aesthetics.
>

Very true.

MDC
--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Bad coding standards - aesthetics are irrelevant

[mark_lundquist]

In article <3A429639.53D3EA9E@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:
> Singlespeeder wrote:
>
> >
> > Unfortunately bad coding style is more than mere aesthetics.
> >
>
> Very true.
>

Though it would be better said "...more than mere cosmetics."

Some of us use "aesthetics" and "programming style" interchangeably --
defined as anything that doesn't in and of itself affect the function
of the program.  So I would would object to the phrase "mere
aesthetics" -- there's nothing "mere" about it! :-)

Cheers,
mark

Mark Lundquist
Rational Software


Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Bruce or Tracy]

I am late on this thread, so pardon me if I am re-stating a point
already made.  I hope I am understanding the original poster's
meaning aesthetics.  

Oh, Hi Stephen!  I was about to agree with you with out realizing who
it was I was agreeing with!

I agree about Ada formatting tool.  

IMHO, Coding Standards and Aesthetics are two separate issues, by the
way.  Coding Standars is like the ole buzz-word "Object Oriented" or
Functionally organized.  Aesthetics are appearance and readability.
However, Aesthetics are NOT irrelevant, and I guarantee you that if the
code
is not readable, it is not easily maintainable.  I am having to maintain
some code right now at work that looks something like this, and I quote: 

  My_Package_Name.My_Procedure_Name (Track_Number,Meters_Till_Impact, 
  Seconds_Till_Impact,Azimuth,Elevation,Range,Delay_In_Seconds);

instead of:

  My_Package_Name.My_Procedure_Name 
    (The_Track_Number        => Track_Number, 
     The_Meters_From_Target  => Meters_From_Targer,
     The_Seconds_Till_Impact => Seconds_Till_Impact,
     The_Weapon_Azimuth      => Azimuth,
     The_Weapon_Elevation    => Elevation,
     The_Weapon_DownRange    => Range,
     The_Seconds_Delay       => Delay_In_Seconds);

Some have even more arguments than this example.  The coders are very
good, smart
coders, they just aren't "tidy", which makes maintenance extremely
difficult, 
especially when you have 400-500 lines of this kind of format in single
procedure.

My $0.02, 
Bruce


William Starner wrote:
> 
> Stephen Leake wrote:
> >
> > "Singlespeeder" <singlespeeder@btinternet.com> writes:
> >
> > > Much of the debate on aesthetics would be needless if there was a good
> > > freely available non-proprietary tool for reformatting the code, much like
> > > the C world has 'indent'.
> >
> > There is. It's called ada-mode for Emacs. Combined with the equally
> > free gnat style checker, it's a great tool.
> >
> > What more do you want?
> 
> Something that works quickly? I use ada-mode, and have that if you want to
> indent a large array initalizer, or something in the area of the large array
> initalizer, it can get as slow as 3 seconds a line, which in the case of a 100
> line array initalizer is terribly slow.
> 
> --
> David Starner - dvdeug@hushmail.com (dstarner98@aasaa.ofe.org off vacation)

Re: Bad coding standards - aesthetics are irrelevant

[Ira D. Baxter]

... and like the C++ world does not have a corresponding tool
because it is hard to do a good job of parsing the langauge
and then prettyprinting.

We are getting set to release a set of prettyprinter programs
based on language parsers, for a number of langauges.
We can do this because we have generalized compiler technology
used for custom analysis/modifications of sources, and
the prettyprinter aspect is sort of necessary "poker ante".

We re trying to gauge interest
in a prettyprinter for Ada.  (We have the Ada83/95 parsers,
not an issue for us).   These prettyprinters won't be
free, but will have an extremely modest price, somewhere
under $100.00.

If you are interested, please let us know, along with any
desiradata.   Depending on interest level, one of
these might be available in a few months.


--
Ira D. Baxter, Ph.D.,CTO           email: idbaxter@semdesigns.com
Semantic Designs, Inc.              web: http://www.semdesigns.com
12636 Research Blvd. C-214    voice: (512) 250-1018 x140
Austin, TX 78759-2200             fax: (512) 250-1191


"Stephen Leake" <stephen.a.leake.1@gsfc.nasa.gov> wrote in message
news:ur931sr3f.fsf@gsfc.nasa.gov...
> "Singlespeeder" <singlespeeder@btinternet.com> writes:
>
> > Much of the debate on aesthetics would be needless if there was a good
> > freely available non-proprietary tool for reformatting the code, much
like
> > the C world has 'indent'.
>
> There is. It's called ada-mode for Emacs. Combined with the equally
> free gnat style checker, it's a great tool.
>
> What more do you want?
>
> > Then all you do is specify a company wide set of flags for the tool
> > and insist that all code is run through the tool with those flags
> > before checking it into the code libraries.
>
> Exactly what our Ada style guide says:
> http://fsw.gsfc.nasa.gov/library/standards.html
>
> --
> -- Stephe

Re: Bad coding standards - aesthetics are irrelevant

[William Starner]

Florian Weimer wrote:
> David Starner <dvdeug@hushmail.com> writes:
> > Something that works quickly? I use ada-mode, and have that if you
> > want to indent a large array initalizer, or something in the area of
> > the large array initalizer, it can get as slow as 3 seconds a line,
> > which in the case of a 100 line array initalizer is terribly slow.
> 
> Have you byte-compiled the Lisp files?

So you haven't seen that? I guess it's possible they aren't byte-compiled, but
they're installed from the Debian package, which means they should. I don't have
access to the computer to check right now. 

-- 
David Starner - dvdeug@hushmail.com (dstarner98@aasaa.ofe.org off vacation)

Re: Bad coding standards - aesthetics are irrelevant

[Simon Wright]

Bruce or Tracy <bljacobs@hiwaay.net> writes:

>   My_Package_Name.My_Procedure_Name (Track_Number,Meters_Till_Impact, 
>   Seconds_Till_Impact,Azimuth,Elevation,Range,Delay_In_Seconds);
> 
> instead of:
> 
>   My_Package_Name.My_Procedure_Name 
>     (The_Track_Number        => Track_Number, 
>      The_Meters_From_Target  => Meters_From_Targer,
>      The_Seconds_Till_Impact => Seconds_Till_Impact,
>      The_Weapon_Azimuth      => Azimuth,
>      The_Weapon_Elevation    => Elevation,
>      The_Weapon_DownRange    => Range,
                                  ^^^^^---------------- probably not!

>      The_Seconds_Delay       => Delay_In_Seconds);
> 
> Some have even more arguments than this example.  The coders are
> very good, smart coders, they just aren't "tidy", which makes
> maintenance extremely difficult, especially when you have 400-500
> lines of this kind of format in single procedure.

I don't see really how you (your company) can know they are
'smart'. Slapdash is not smart.

One of my mentors used to refuse to look at documents with untidy
diagrams (this was in the days when the diagrams had to be drawn on
the stencil by hand) on the grounds that if you couldn't be bothered
to produce tidy work you probably hadn't bothered with the content
either.

Of course you have to be wary of the 'whited sepulchre', but in my
experience incompetents don't succeed at producing them either!

I noticed the 'The_Whatever' style -- this was the old Booch
recommendation, I think. But even then it struck me as a desperate
measure -- really you need to think about the names in the context
that the subprogram must be called. Not always possible, of course!

Re: Bad coding standards - aesthetics are irrelevant

[mark_lundquist]

In article <x7vr92zwokn.fsf@smaug.pushface.org>,
  Simon Wright <simon@pushface.org> wrote:
> Bruce or Tracy <bljacobs@hiwaay.net> writes:
> >
> >   My_Package_Name.My_Procedure_Name
> >     (The_Track_Number        => Track_Number,
> >      The_Meters_From_Target  => Meters_From_Targer,
> >      The_Seconds_Till_Impact => Seconds_Till_Impact,
> >      The_Weapon_Azimuth      => Azimuth,
> >      The_Weapon_Elevation    => Elevation,
> [etc...]
>
> I noticed the 'The_Whatever' style -- this was the old Booch
> recommendation, I think. But even then it struck me as a desperate
> measure -- really you need to think about the names in the context
> that the subprogram must be called. Not always possible, of course!
>

Yeah!  I can't stand the "The_Whatever" style, either.  I never, ever
use it.  "Desperate" is just the right for how it reads.  Did that
really come from His Boochness? :-)

The funny thing about the example is that is the named associations,
which are (rightly) being displayed as an example of improved
readability, that make the weakness of the "The_Whatever" convention
most apparent.  This habit is an easy way out for the writer of the
parameterized construct at the expense of the writer who will use it.


Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Erik Magnuson]

In article <3A429639.53D3EA9E@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:
> Not everything about style - including asthetics - can be resolved
effectively
> by a machine. For example, you might have an identifier: Rotor_RPM.
Automatic
> case rules would have a hard time noting that RPM is an abbreviation
and
> should be upper case. Or it could just preserve case as it was given,
but then
> what stops someone from writing rotor_rpm which might violate the
coding
> conventions?

Way back when I wrote* an Ada pretty-printer, I used a simple rule:
Preserve the case of the 1st usage you see for each identifier and make
all the rest conform to that case. If you were processing multiple
files, you could "seed" the pretty-printer with exceptions like
Rotor_RPM. The other common approach is to have a second pass change
all of the project std. acronyms, but I thought my approach was more
general.

--
Erik

* OK, I did not write it from scratch. I modified one of the ones from
the old Ada source code archive.


Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Marin David Condic]

While one can always come up with creative solutions to this sort of thing,
I think it still remains that there are going to be things about coding
style and conventions that cannot be solved by algorithm. This is
especially true where you get away from pure syntax and start to touch on
semantics. "Adhere to such-and-such convention whenever an object refers to
so-and-so..." (A certain class of constants or data items, for example.)

The method you propose would work, provided that all programmers on a
project correctly capitalized (according to project norms) their first use
of an identifier or, as you say, create a single file that contains the
most common acronyms, etc. It doesn't work the instant someone violates the
conventions on a first occurence.

Identifier capitalization is just one instance where automation can't
universally apply and definitely not the best example because there are
ways of at least mostly-automating it with some possible human
intervention. There are others that can't be dealt with as easily.

MDC

Erik Magnuson wrote:

> Way back when I wrote* an Ada pretty-printer, I used a simple rule:
> Preserve the case of the 1st usage you see for each identifier and make
> all the rest conform to that case. If you were processing multiple
> files, you could "seed" the pretty-printer with exceptions like
> Rotor_RPM. The other common approach is to have a second pass change
> all of the project std. acronyms, but I thought my approach was more
> general.

--
======================================================================
Marin David Condic - Quadrus Corporation - http://www.quadruscorp.com/
Send Replies To: m c o n d i c @ q u a d r u s c o r p . c o m
Visit my web site at:  http://www.mcondic.com/

    "Giving money and power to Government is like giving whiskey
    and car keys to teenage boys."

        --   P. J. O'Rourke
======================================================================

Re: Bad coding standards - aesthetics are irrelevant

[Robert Dewar]

In article <3A4B9FB8.AFD69726@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:
> Identifier capitalization is just one instance where
> automation can't universally apply.

I hope everyone realizes that one of the arguments in favor of
all upper case identifiers is precisely that auomation CAN
universally apply to identifier capitalization if you use this
convention.

The other argument in favor of all upper case identifiers is
that they stand out more clearly in comments.

These are not decisive arguments, just some relevant ones :-)


Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Larry Kilgallen]

In article <3A4B9FB8.AFD69726@acm.org>, Marin David Condic <mcondic.nospam@acm.org> writes:

> The method you propose would work, provided that all programmers on a
> project correctly capitalized (according to project norms) their first use
> of an identifier or, as you say, create a single file that contains the
> most common acronyms, etc. It doesn't work the instant someone violates the
> conventions on a first occurence.

No, that is the point at which it _does_ work, by making it obvious at
_all_ instances (to a caring human) that a correction is needed.

Re: Bad coding standards - aesthetics are irrelevant

[Tarjei T. Jensen]

Marin David Condic
>Identifier capitalization is just one instance where automation can't
>universally apply and definitely not the best example because there are
>ways of at least mostly-automating it with some possible human
>intervention. There are others that can't be dealt with as easily.

Quite the opposite I should think. As long as one uses the way it is written in
the declaration then there should be no problem.

The disadvantage is that the prettyprinter would have to know where to obtain
the declaration and parse the relevant files to obtain the information. This is
of course very easy :-)

Apart from that the first occurence rule sounds very reasonable.

Failing that the ada vendors could agree on a convention for special comments
to be used for pretty printing directives. E.g.

-- ## PP appearance Rotor_RPM <bold times-roman 18pt>

Re: Bad coding standards - aesthetics are irrelevant

[Erik Magnuson]

In article <3A4B9FB8.AFD69726@acm.org>,
  Marin David Condic <mcondic.nospam@acm.org> wrote:
> While one can always come up with creative solutions to this sort of
thing,
> I think it still remains that there are going to be things about
coding
> style and conventions that cannot be solved by algorithm.

I agree you cannot automate everything. But I also think that you
should automate what you can so that you can devote more attention to
the rest. After all, if your pretty-printer already matches your style
guidelines, running it will either make no changes at all or just fix a
few minor mistakes.

While the "preserve 1st use" rule was not perfect, it was both easy to
implement and worked most of the time. Who was it that said, "Better is
the enemy of good enough?"

--
Erik


Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Robert Dewar]

In article <92i5hu$ktl9@news.kvaerner.com>,
  "Tarjei T. Jensen" <tarjei.jensen@kvaerner.com> wrote:
> Failing that the ada vendors could agree on a convention for
> special comments to be used for pretty printing directives.

I assume everyone in this thread is familiar with the GNAT
convention (implemented by the -gnatyk switch) is that all
uses of an identifier must match the casing of the declaration.

(I think declaration is a better criterion than first use,
and they are not quite equivalent when you have multiple
units).

Also we have seen cases where two identifiers have the same
characters but different casing, e.g.

   Unval
   UNval

where perhaps the Un in the first one is Un as in Untie,
and the UN in the second is UN as in United Nations.

In GNAT, each reference will be forced to be cased
appropriately (and of course you really need a compiler
with full visibility analysis to do this right).


Sent via Deja.com
http://www.deja.com/

Re: Bad coding standards - aesthetics are irrelevant

[Wes Groleau]

> > Then all you do is specify a company wide set of flags for the tool
> > and insist that all code is run through the tool with those flags
> > before checking it into the code libraries.
> 
> Exactly what our Ada style guide says:
> http://fsw.gsfc.nasa.gov/library/standards.html

But using a particular compiler (good as it is) as your
pretty printer risks difficulties using another compiler
that doesn't have the same bugs.

(i.e., it maybe a certain construct, legal or not, crashes
GNAT, but the alternative crashes Apex.  I've seen it happen!)

-- 
Wes Groleau
http://freepages.rootsweb.com/~wgroleau

Re: Bad coding standards - aesthetics are irrelevant

[Wes Groleau]

> by a machine. For example, you might have an identifier: Rotor_RPM. Automatic
> case rules would have a hard time noting that RPM is an abbreviation and
> should be upper ....

If the "pretty printer" also does a spellcheck on every "word" in every
identifier, the algorithm could be

  if in standard dictionary, initial caps
  if in approved exceptions, case exactly as in list
  else flag as violation

This is still not foolproof--you have to be careful not to
approve an acronym that is also a regular word.  

You also need to avoid the process used by some:

  if not on list of approved abbreviations then
     add to list of approved abbreviations
  end if

:-) :-)

-- 
Wes Groleau
http://freepages.rootsweb.com/~wgroleau