Comments at the End of Lines

Comments at the End of Lines

[Roger Racine]

Are comments at the end of lines frowned upon for some reason?  The latest 
version of AdaGIDE, during a reformat, moves all such comments to the next 
line.  The statistics program provided by it gives incorrect results when 
end-of-line comments exist.

Finally, not related to Ada, a C style guide I was asked to review had a rule 
that said not to put comments at the end of lines.

Perhaps there is a good reason for this rule, but I can not think of one 
(other than making a statistics tool easy to write by just looking for 
semicolons at the end of lines).

Roger Racine

Re: Comments at the End of Lines

[John Duncan]

> Finally, not related to Ada, a C style guide I was asked to review had a
rule
> that said not to put comments at the end of lines.

I'm not exactly sure, but if you consider the C example, comments on the
same line tend to be used to "explain" a very mangled semantic structure. As
far as the meaning of each line is concerned, you shouldn't need comments at
the end of the line. Consider:

Beta := Sqrt(X); -- Assign sqrt(x) to beta

There are a lot of programmers who are told to write comments and put these
things in. It's not good style, obviously. What is good style
is something like:

Obscure := Strange(Odd); -- This actually gets translated to Greek.

When you have something weird to explain that you can't escape.
There's a problem, though, that the space between the semi and the margin is
very small, and you can't explain very well. This example may have been
better as:

Obscure := Strange(Odd);
    -- This actually gets translated into ancient Greek c. 230BC.
    -- Homer wrote the function and no one knows what it does,
    -- but it has faithfully produced the correct value each time.

So that's the best I can do:)

-John

Re: Comments at the End of Lines

[Robert Dewar]

In article <7lir0r$og1$1@usenet01.srv.cis.pitt.edu>,
  "John Duncan" <jddst19+@pitt.edu> wrote:
> > Finally, not related to Ada, a C style guide I was asked to
> review had a
> rule
> > that said not to put comments at the end of lines.

Perhaps they were afraid of

   *p = 3;
   x = 5/*p;

:-)


Sent via Deja.com http://www.deja.com/
Share what you know. Learn what you don't.

Re: Comments at the End of Lines

[Robert Dewar]

In article <7lir0r$og1$1@usenet01.srv.cis.pitt.edu>,
  "John Duncan" <jddst19+@pitt.edu> wrote:
> > Finally, not related to Ada, a C style guide I was asked to
> review had a
> rule
> > that said not to put comments at the end of lines.

Perhaps they were afraid of

   *p = 3;
   x = 5/*p;

:-)


Sent via Deja.com http://www.deja.com/
Share what you know. Learn what you don't.

Re: Comments at the End of Lines

[Steve Doiel]

John Duncan wrote in message <7lir0r$og1$1@usenet01.srv.cis.pitt.edu>...
>> Finally, not related to Ada, a C style guide I was asked to review had a
>rule
>> that said not to put comments at the end of lines.
>
>I'm not exactly sure, but if you consider the C example, comments on the
>same line tend to be used to "explain" a very mangled semantic structure.
As
>far as the meaning of each line is concerned, you shouldn't need comments
at
>the end of the line. Consider:
>
>Beta := Sqrt(X); -- Assign sqrt(x) to beta
>
You'll have a hard time persuading me that you need comments on separate
lines for the following code (declarations).

  pieceLength  : Float; -- inches
  pieceArea     : Float; -- square feet
  pieceVolume : Float; -- cubic feet

SteveD

Re: Comments at the End of Lines

[Chad R. Meiners]

> You'll have a hard time persuading me that you need comments on separate
> lines for the following code (declarations).
>
>   pieceLength  : Float; -- inches
>   pieceArea     : Float; -- square feet
>   pieceVolume : Float; -- cubic feet
>
> SteveD

Wouldn't it be better to declare ADT's for the units of measurement?  You
could then write the declarations like this:

pieceLength   : Inches;
pieceArea      : Square_Feet;
pieceVolume  : Cubic_Feet;

You then can have proper type check since I cannot think of a reason why you
would want to assign a volume to  length.  Not to mention that the remarks
are now unnecessary.

-Chad R. Meiners

Re: Comments at the End of Lines

[John Duncan]

> You'll have a hard time persuading me that you need comments on separate
> lines for the following code (declarations).
>
>   pieceLength  : Float; -- inches
>   pieceArea     : Float; -- square feet
>   pieceVolume : Float; -- cubic feet

Yes, this is a good example. I didn't write the style guide, you know, I
just tried to come up with justifications for certain rules. In C, the norm
tends to be more like:

float lp; /* length of piece in inches */
float ap; /* area of piece in ft^2 */
float vp; /* volume of piece in cu. ft. */
struct tag_MyS *lpMyS; /* a thingy */
struct tag_MyS **apMyS; /* a whole bunch of thingies */

Ada differs from C both in its language form and in its starting point for
expressive style. The RM95/Rat95 have understandable style. I imagine,
though I have not looked, that RM83 also did. But K&R followed Kerninghan's
diseased "short identifiers only" rule. The only good reason I can think of
for K&R's style is that the Decwriter was a hardcopy terminal, and that is
what they were using at the time. Better to make short identifiers that you
won't occasionally misspell and have to edit (using ed).

One problem that I have with your declaration up there is that you move from
inches to feet. If your lengths are in inches, why are your areas not in
inches? I would think it funny to see an area function that looked like
this:

-- linear values are in inches, area returned in sq. ft.
function Area(L: Float, W: Float) return Float is
begin
    return ((L * W) / 144); -- must convert after calculation
end Area;

Rather, I would imagine that you would normally do it like this:

function Area(L: Float, W: Float) return Float is
begin
    return L * W;
end Area;

function Sq_Inches_To_Sq_Feet(X: Float) return Float is
begin
    return X / 144;
end Sq_Inches_To_Sq_Feet;

The first method could be a real screw to someone who justifiably did not
read through the whole package to find out that in order to calculate an
area, the linears must be in inches, and the result must be in sq. ft.
Without the dependency on units, the functions are generic, and will work
for cm. and parsecs alike. If someone were to need a conversion function:

function Light_Years_To_Inches(X: Float) return Float;

They could easily overflow the value before the calculation. Plus, when
measuring light years, they will most likely not be using inches except in
this hypothetical area calculation.

I don't know. In the end your example doesn't elucidate a very good reason
for the things after all. I think that it matters more with declarations
like this:

Concentration: Float; -- molarity

because there are a good number of accepted ways of measuring concentration,
including PPM, molality, and percentage, and it matters more for the
application than anything else.

Another example of where it would be useful would be:

with PhysicalConstants;
G: constant Float renames PhysicalConstants.G; -- m^3/(kg*s^2)

because the reader may not be sure as to whether the G being brought in is
MKS, CGS, or customary. It may not be useful because the organization uses
only CGS, regardless of the calculation.

-John

Re: Comments at the End of Lines

[Steve Doiel]

[snip]
>
>One problem that I have with your declaration up there is that you move
from
>inches to feet. If your lengths are in inches, why are your areas not in
>inches? I would think it funny to see an area function that looked like
>this:
>
>-- linear values are in inches, area returned in sq. ft.
>function Area(L: Float, W: Float) return Float is
>begin
>    return ((L * W) / 144); -- must convert after calculation
>end Area;
>
>Rather, I would imagine that you would normally do it like this:
>
>function Area(L: Float, W: Float) return Float is
>begin
>    return L * W;
>end Area;
>
I agree that it seems odd that length is maintained in inches while area is
maintained in square feet.  But in certain industries this as a "standard"
convention.

BTW: I didn't really want to get into it with regard to the placement of
comments but what is perhaps a better answer to the unit question is to
declare different types for each unit and provide overloaded math functions
that implicitly convert dimensions.

SteveD

Re: Comments at the End of Lines

[Larry Kilgallen]

In article <377e3757.0@news.pacifier.com>, "Steve Doiel" <nospam_steved@pacifier.com> writes:

> You'll have a hard time persuading me that you need comments on separate
> lines for the following code (declarations).
> 
>   pieceLength  : Float; -- inches
>   pieceArea     : Float; -- square feet
>   pieceVolume : Float; -- cubic feet

You will have a hard time persuading me that those should not be
declared as separate types, regardless of how they are commented.

Larry Kilgallen

Re: Comments at the End of Lines

[Martin C. Carlisle]

In article <rracine.20.00079751@draper.com>,
Roger Racine <rracine@draper.com> wrote:
>Are comments at the end of lines frowned upon for some reason?  The latest 
>version of AdaGIDE, during a reformat, moves all such comments to the next 
>line.  The statistics program provided by it gives incorrect results when 
>end-of-line comments exist.
>Roger Racine

No, although I tend not to use them.  There didn't seem to be a good 
reason to have the reformatter do this, so I changed it to allow end 
of line comments.


One of our faculty gave the counter as an assignment in a course
here at the Academy.  I got a copy of his solution a couple of years ago for
a specific purpose.  He left, and then we started using PSP.  One
person suggested it would be nice to have a tool in AdaGIDE that counted 
lines.  I remembered I had this lying around and put in in.

Alas, I do not have the sources, so I can't fix the problem that
end of line comments are perceived as comment lines.  Perhaps I need
to give the assignment again :-).  Or, maybe one of those people looking
to hone their Ada skills could contribute it.

--Martin



-- 
Martin C. Carlisle, Asst Prof of Computer Science, US Air Force Academy
carlislem@acm.org, http://www.usafa.af.mil/dfcs/bios/carlisle.html
DISCLAIMER:  This content in no way reflects the opinions, standards or 
policy of the US Air Force Academy or the United States Government.