Re: Commenting in Java



Chris Uppal wrote: 

But....

Did the software depend in any way of the prime-ness of HASHSIZE ?  If so, was
that obvious from the code alone (and not via an additional step: "Ah I
recognise this as <such-and-such> algorithm, and I happen to know that only
works well with primes") ?  If not, then how would you have known that the
author had made a mistake ?

I can tell the story of a similar mistake that I once made, that (had it not
been caught by an eagle-eyed college -- who /read/ the comments and compared
them with the code) might have had Very Serious Consequences for the company I
worked for.

Redundancy is good.  The /reason/ it's good is that errors can be detected, and
ambiguities resolved.  In
the case of comments, that means that the possibility of divergence between
code and comment is (one of the many) /advantages/ of commenting, not a
disadvantage.

Redundancy is good when comments are correct. But if comments are wrong you might waste a lot of time trying to find out how the code can do what is told in the comment, when it's actually doing something different, For example, the author might have wanted, at the beginning, to use a prime number. After that he changed his mind, but not his comment. This makes you think "why did he put this comment? 51 is not prime. And why would I need a prime anyway?" (by the way, why do I need a prime? Is it related to the hash size?). Of course, you also think "maybe the comment is wrong", but you just spend more time checking and rechecking that you understand the code correctly, and that the comment is wrong. Not to mention, of course, the case when you trust a wrong comment.
Now, don't misunderstand me, I like comments, and documentation. But comments do have a drawback. Comments are good, too many comments sometimes are not.
.

Relevant Pages

  • Re: Why do so few people know the difference between arrays and pointers.
    ... Only after you made a serious mistake or saw the outcome ... > algorithm - even though he theoretically knew it beforehand. ... an algorithm with higher time complexity may be faster than one of ... log^2 ) nanoseconds, and method B taking N^0.7 nanoseconds. ...
    (comp.lang.c)
  • Re: How to calculate SNR for signal which can only detect with noise?
    ... Someone suggest that for signal which we can only detect with noise, ... source and add some kind of synthesized noise to verify our algorithm. ... do you *know* exactly what signals the data contains, ... "Prejudice" in this context is the mistake of thinking some method ...
    (comp.dsp)
  • Re: Chaum-van Heijst-Pfitzmann hash function
    ... I admit my mistake and hope that you accept my apologies. ... I can't blame this hash function for my silly mistake of choosing a too ... This doesn't mean that I have lost my trust for the algorithm itself. ... And a security-related algorithm appears much more ...
    (sci.crypt)
  • Re: A Poetic Tribute To D. Spencer Hines
    ... A wonderful piece of irony. ... But still make the mistake of failing to recognise the difference ...
    (soc.genealogy.britain)
  • Re: is this legal?
    ... discussion, because a photograph is a piece of evidence, just as much ... and recognise it as one ... that downloading the pics, and getting caught taking those pics in the ... shopping centre, was not a mistake. ...
    (uk.legal)