Re: Documenting Code (was:Programming language vote - results)

[Alan E & Carmel J Brain <aebrain@dynamite.com.au>]

Don Guinn wrote:

> > Don Guinn wrote:
> > Why is it OK to spend a whole morning understanding a couple pages of
> > FORTRAN code, yet it is unreasonable to spend the same amount of time
> > with a 2-liner in APL or J which does the same thing?

> > I prefer to use APL but I have long ago realized that it is beneficial to
> > spread it out a bit rather than use very complex 1 or 2 liners.

> You are right.  It does make it easier to read if things are spread out.

> As far as documenting code.  Documentation is wonderful when it adds
> information and insight on what the program does.  I have seen too many
> programs full of documentation which does nothing but repeat what is
> already stated in the code itself.  It's as if the person who wrote it
> can't read his own code.

> Documentation needs to explain the concepts used in an application.  It
> should provide definitions of terms (variables) and possible things to
> watch out for.  But it should not have to translate the source code into
> English.  It should not be measured by the pound.

My viewpoint:

If one is using a language that is "terse", such as APL, where WHAT the
thing does is not immediately obvious, then a quickly-read line which
explains what the code is _supposed_ to be doing is very helpful. At
first glance, it can tell a reader what the code does, more quickly than
ploughing through cryptic things like

GHTransmit(const char* const X);

which is basically a read-only string input to a function.

Secondly, comments often tell what the program is _supposed_ to do, not
always what it does. This means that a quick-scan of the comments only
will not reveal a bug. OTOH a more careful reading, which would reveal
the difference between actual and intended, automatically finds the bug
and suggests a solution.

OK, that's it for documenting WHAT the code does. In many, less terse
languages, comments are more useful for describing _why_ something is
done. For example (in Ada-83);

with Tracker;			-- package for Radar Trackers only!
with TacticalPicture;           -- what's the environment we're in

procedure AllocateRadarTrackers
(TheTrackerStates         in Tracker.StateTableType,
 TheTacticalPicture       in TacticalPicture.BasicRecordType,
 ResultantTrackerCommands out Tracker.CommandListType)
is
-- Procedure that, given a table of the current radar tracker
-- states, and the tactical picture, decides on what commands
-- to give to the radar trackers.
-- These commands are then expected to be transmitted to the
-- trackers by another procedure.
-- Exceptions that can be raised here are:
--   AllTrackersKaputException ( The Trackers are all KO )
--   UnexpectedErrorException  ( Bug or hardware fault)

begin
  -- and so on and so on
end;

Note that in this (deliberately) verbose and non-terse example, the
variables, procedure, exception and type names are self-explanatory.
To some degree, the code _is_ the comment, at least on "what it does".
Most of the comments "as such" are either explanations of the intention,
or give implications of events.

A terser piece of code that is exactly hemeomorphic is:

with Trk;
with TacPic;
procedure TCmds ( T in Trk.Lst, TP in TacPic.TP, Cmds out Trk.Cmds )
is
-- Procedure that, given a table of the current radar tracker
-- states (Trk.Lst), and the tactical picture (TacPic.TP), decides on
-- what commands to give to the radar trackers (Trk.Cmds).
-- These commands are then expected to be transmitted to the
-- trackers by another procedure.
-- Exceptions that can be raised here are:
--   ATK ( _A_ll _T_rackers _K_O )
--   FUBAR  ( Bug or hardware fault)
begin
-- etc etc
end;

Note that despite some bad names, the comments explain what's happening.
Without the comments, this would be so cryptic as to be baroque. A
translation into C++ would be something like

#include TP.h;  // Tactical Picture Class
#include Trk.h; // Tracker Class

Trk::CmdList* TCmds( const Trk::Lst* const TL, const TP::Data* const TP)

// Procedure that, given a table of the current radar tracker
// states (Trk::Lst), and the tactical picture (TP::TP), decides on
// what commands to give to the radar trackers (Trk::Cmds).
// These commands are then expected to be transmitted to the
// trackers by another procedure.
// It's assumed that TL and TP are both going to be used later, so
// the pointers have been made const, as well as the data pointed to.
// Exceptions that can be thrown here are:
//   ATK ( _A_ll _T_rackers _K_O )
//   FUBAR  ( Bug or hardware fault)

{
 // etc etc
}  

When using Hungarian Notation, a lot more verbosity sneaks in, as in the
first Ada example, which has an equivalent of Hungarian Notation in it ( 
Tracker.StateTableType rather than Tracker.State for example)

How NOT to do it (in any language):

procedure P_12_356( X99 in integer )
is
  NumberOfBananas : integer; -- The number of Bananas
  NumberOfBaskets : integer; -- The number of Baskets
  F : float;
begin
 -- and so on in this deliberately BAD example
 -- which shows that it's possible to write really bad Ada,
 -- and make comments that are both verbose and useless,
--  but you have to really, really work at it!
end;

I still for the life of me can't understand why C++ is so popular, yet
Ada is described as obsolete, etc etc when for a lot of purposes, Ada is
C++ with (usually more) clarity, power and safety belts. Certainly in my
experience C++ programmers who've had some exposure to Ada have an
advantage over the rest. But never mind.
--     
aebrain@dynamite.com.au     <> <>    How doth the little Crocodile
| Alan & Carmel Brain|      xxxxx       Improve his shining tail?
| Canberra Australia |  xxxxxHxHxxxxxx _MMMMMMMMM_MMMMMMMMM
 abrain@cs.adfa.oz.au  o OO*O^^^^O*OO o oo     oo oo     oo  
                    By pulling MAERKLIN Wagons, in 1/220 Scale