Re: Comments at the End of Lines

["John Duncan" <jddst19+@pitt.edu>]

> 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