"How to Comment Code"

"How to Comment Code"

[Ken Garlington]

While I agreed with much of your article "How to Comment Code" in the 
March 1996 Embedded Systems Programming, I did have some concerns with 
your examples.

1. The comment for the call to "initialize_port" appeared to duplicate
the description in its definition. Generally, it would be better to
define the interface in one place only, to minimize the amount of
work needed if that interface changes.

2. Having comments in one block of code that describe the behavior of a 
different block of code (the "check_for_debugger" reference) can also 
cause significant maintenance problems.

3. Interface comments should avoid references to the internal workings 
of the code (the "baud_rates array" reference) for the same reason.

I also thought that you should have emphasized the impact of source 
language on the method of commenting. Some embedded system languages, 
such as Ada, allow the explicit declaration of many of the attributes 
you defined as "C" comments. This makes the code more self-documenting, 
and it allows the compiler to find cases where the user failed to 
understand the "comments".

For example, the following code, which is equivalent to your "C" 
examples, actually requires very few "comments" in the traditional 
sense.

package Serial_IO is

  type Port_Type is range 0 .. 10; -- assuming MAX_SIO_PORTS was 10

  subtype General_Purpose_Port_Type is Port_Type
    range Port_Type'First .. Port_Type'Last-1;

  subtype Remote_Debugging_Port_Type is Port_Type
    range General_Purpose_Port_Type'Last+1 .. Port_Type'Last;

  type Baud_Rate_Type is (Baud_300, Baud_1200, Baud_2400, Baud_4800,
                          Baud_9600, Baud_19200, Baud_38400);

  type Bits_Count_Type is range 7 .. 8;

  type Parity_Type is (None, Even, Odd);

  type RTS_Status_Type is (RTS_On, RTS_Off);

  procedure Initialize_Port    -- also reset the UART
  (
    Port_ID    : in General_Purpose_Port_Type;
    Baud_Rate  : in Baud_Rate_Type;
    Data_Bits  : in Bits_Count_Type;
    Parity     : in Parity_Type;
    RTS_Status : in RTS_Status_Type
  );

end Serial_IO;

with Serial_IO; use Serial_IO;
procedure Initialize_Ports_to_Default_Values is
begin

  for Port in Serial_IO.General_Purpose_Port_Type loop
    Serial_IO.Initialize_Port
    ( Port_ID    => Port,
      Baud_Rate  => Baud_9600,
      Data_Bits  => 7,
      Parity     => None,
      RTS_Status => RTS_Off
    );
  end loop;

end Initialize_Ports_to_Default_Values;