Hi all,
Just a bit of further follow-up to my earlier mail, on the topic of
the proliferation of XXX comments (that have not traditionally been
sprinkled throughout PCP), but which seem to be arriving a bit more
from certain quarters now.
In general, such XXX comments (we have none, nada, zero of these in
libpcp currently) should have a very good reason for existing. There
should be very few of them, or something is very wrong (maybe code was
merged before it was not ready? I'm certainly guilty of that). They
should have a clearly-defined exit strategy, such that code can move
*toward* clarity, rather than away from it as more XXXs accumulate over
time.
Code with explicit issue tracker numbers may be OK (prefer the fix!) -
and detailed discussions can live there. Chatty opinions about code, or
notes that someone else should document something better? ... that's not
helpful.
Otherwise, we end up with incomprehensible ramblings like this gem, where
even the author doesn't seem to know how the code works:
// error already noted XXX where?
goto out0;
Amongst some 26 other XXXs in that particular utility, hmm. Clearly
this is a coding-stylistic thing for some folk and not others, but it
makes the code alot less readable - to my eye anyway. Tends to make me
think, "did the author know what they were talking about", "is it still
relevant today, ten years later", "why not fix it up-front", etc. And
evidently everyone else working on libpcp for the last 20 years shares
that kind of thinking.
So, please refrain from adding these comments if possible, or do so with
care, thinking of other people who will be reading them (possibly a long
time in the future). And please actively look to remove these XXX notes
wherever you can - clean code, its the PCP way. :) Thanks!
cheers.
--
Nathan
|