Re: marking mystery code

dewar@cs.nyu.edu (Robert Dewar) wrote:


[snip]


> Incidentally, the practice of marking suspicious code seems a good one
> to me. If code is being read by more than its author (often sadly not
> the case), then a reader will often wonder what something means, and
> not necessarily be able to tell if it is a bug, or if it needs more
> documentation, or perhaps some invariant that is assumed is not 100%
> right etc.
>
> In GNAT we use ??? for this purpose, and there are quite a few ???
> around the place. I suspect that nearly all large projects have
> numerous instances of code which merits the ??? mark, but they don't
> get marked.


> In GNAT, each ??? is a potential bug. It could be an out-and-out bug,
> or just an obscure case not covered, or simply a lack of
> documentation, or a case where the code is not wrong, but can be
> cleaned up. Of course the idea is that ??? comments eventually
> disappear -- they are essentially low priority bugs, which have not
> showed up in any test program, and perhaps could NOT result in a
> failure, but nevertheless should be fixed.


> I find that the systematic attempt to clean up such spots in code,
> even if not driven by bug reports, is a way of aiming at higher
> quality, and is a practice that much code in the field that I see
> could benefit from.


Amen. In code I maintain myself the mark is "FIXME", in code I
maintain with others, the mark is "FIXME KPD" so we'll know who asked
the question. This suffices for that coding pass that says "get it
working at all", and marks in particular places where the spec wasn't
clean enough to become code assured of matching the spec's intention,
but I'm not about to lose hours of hard won in-skull context to get up
from my desk and chase down the authority on that particular intension
right at the moment. Later, in the "get it working right" phase, this
mark is the place to start looking when anticipated problems in fact
arise.


More than a mere "???" one place, I use FIXME's like this:


-- FIXME KPD This may or may not be what John meant by "throw all the values
-- FIXME KPD in a bag and shake well"; clarify later.


The point being that by having a "FIXME" on each line, grep() on all
the source files will give me a nice report of the whole comment, not
just its first line.


For stuff I really don't know how to fix, and where writing an English
description that works without the code context when pulled out by grep()
is almost as hard as understanding what might be wrong, I sometimes also
provide a context mark:


-- FIXME KPD CONTEXT ContainerInstance.bag += item;
-- FIXME KPD CONTEXT ContainerInstance.randomize();


(excuse the mixed coding metaphor) with a copy of the scrap of code
that is giving me heartburn, so that grep() pulls out both comment and
code copy context of the comment in some useful order.


This is a _huge_ win when trying to remember later where it was I saw
the suspect code that has only now proven itself buggy [say, in my
dreams, by crashing the Mars lander in a simulator run].


[The ability found, say, in emacs(), to set a line prefix and then
flow paragraphs with that prefix is a must for doing this kind of
problem marking style without intense editing pain, of course.]


Other's may perfer Robert's more lightweight potential problem marking
system, but I type fast enough to invest in FIXMEs.


--
Xanthian.
Kent, the man from xanth.
Kent Paul Dolan
xanthian@{well,qualcomm}.com
[Interesting though this is, it's drifted away from compilers so I've aimed
followups elsewhere. -John]
--

Return to the comp.compilers page.
Search the comp.compilers archives again.