Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!rutgers!uwvax!oddjob!tank!uxc!uxc.cso.uiuc.edu!uxg.cso.uiuc.edu!uicsrd.csrd.uiuc.edu!jaxon
From: jaxon@uicsrd.csrd.uiuc.edu
Newsgroups: comp.lang.apl
Subject: Re: debuggers
Message-ID: <49700005@uicsrd.csrd.uiuc.edu>
Date: 18 Oct 88 16:38:00 GMT
References: <109@infbssys.infbs>
Lines: 53
Nf-ID: #R:infbssys.infbs:109:uicsrd.csrd.uiuc.edu:49700005:000:2753
Nf-From: uicsrd.csrd.uiuc.edu!jaxon    Oct 18 11:38:00 1988


>> Rarely comment on the code itself.

I would go farther than that: NEVER leave a comment that merely restates
what the APL code is doing.   When you are hunting down bugs later on, 
there is a huge temptation to BELIEVE such comments when your code in
fact does something else.  Worse still, if the code is right and the
comment is inaccurate, you stand a chance of misusing the function or of
"correcting" it to match the (erroneous) comment.

The little "lamp" symbol is intended to light your way through the code.
I generally use it to describe the goal of the next several function lines.


Comments that describe a function's arguments, result and (do you really
use?) global side-effects  should meet the same criteria:  State the
purpose of the argument, not the rules for what is and isn't a legal
argument.   I've always been torn between the higher performance of
a one-liner utility routine that expects its caller to supply correct
arguments and the safety of a routine that checks everything before it
does its job.  Every program has different needs , and fortunately APLs
offer a couple of approaches.

    1)  #ER or #ERR or some such system function that raises a regular
       APL error signal.  When Steve Bartels and I designed APLB we put in
       a #ER that does nothing if its argument is empty and otherwise signals
       an error with the argument as the error message.  We use it for
       ASSERTION CHECKING, for example:

       #ER (~2|ARG)/'THE LEFT ARGUMENT MUST BE A SINGLE ODD INTEGER'

    2) Sometimes the checks take more time than the function.  I can't
       stand the thought of clogging a perfectly clear one-liner with
       inane tests.  In these cases I write a "cover function" that
       does all the inane tests, then calls my one-liner.  When I want the
       high performance version I )COPY in a group that replaces
       the cover functions by their formula 1 race car guts.  (Seat belts
       not available.)

    3) APL primitives do a lot of checking themselves.  In the above
       example I checked for odd ARGs, but the APL "not" (~) checked 
       for integers, and the "replicate" (/) gets some length or rank
       error if ARG isn't scalar (or exactly the length of my message).
       The important thing is that the program stops on a line that
       expresses some constraint that has been violated, or some 
       assumption that turned up false.   Errors reports are our friends!
       ...well more like relatives actually...

Comments have never done much for me, I only believe what I read in
the code.  So when I need support to believe that the code is correct
I write code that documents my intentions, not comments.

regards - Greg Jaxon  (jaxon@uicsrd.uiuc.edu)