Re: Easily-Read C++?

[Bob Wells #402 <wel@EUROCONTROL.DE>]

Robert Dewar <dewar@CS.NYU.EDU> writes .....

> Subject: Re: Easily-Read C++?
>
> There are to my mind three justifications for comments:
>
> Saying WHY you are doing something, and WHY you did it that way
>
> Saying WHY you did NOT do something, and WHY you did NOT
>
> Describing WHAT the code does, but at a higher level of abstraction
> than the code itself.

G'day Robert,
I totally agree with the above justifications and would also add the
following two:

Describing assumptions about the format or structure of an external
interface, e.g. an incoming message.

-- STAMINA message originator format
-- ORIG/ROLE/HQ

Describing the corresponding meaning for values when they are
defined. For example.

-- The following corresponds to the field RBT in the STORE.QTID section of
-- the PEAQTID file when the TYP field contains a 1 and RBN /= 0.
--
type Rlb_Data is ( Sdd_Coordinates,
                   Plot_Identification,
                   Track_Identification,
                   Sdd_Test_Picture_Display,
                   Track_Id_Or_System_Coordinates,
                   System_Coordinates,
                   Ssr_Code );

Regards,
Bob W. (-: