Re: Commenting in Java

Eric Sosman wrote:

> My favorite comment of all time was found by a colleague
> debugging someone else's C code:
>
> #define HASHSIZE 51 /* a small prime */

;-)


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.

-- chris




.

Relevant Pages

  • Re: Java regex syntax
    ... writing does not qualify as context provided by you. ... Eric Sosman is one of the gurus of this space, never mistaken that I've caught and always willing to go out of his way to help folks in these fora. ... a mistake you haven't been paying attention ... ...
    (comp.lang.java.programmer)
  • Re: DataTable.select problem with variables
    ... We have ways of parameterizing queries ... I found the mistake after adding the single quotes i gave a space and ... while debugging it doesn't show the space(unable ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: Young Israel moves right and some synagogues rebel
    ... On Jul 5, 6:05 pm, Giorgies E Kepipesiom ... let us not make any mistake about it. ... Schach ... How do you say in Hebrew "my colleague," Amitai? ...
    (soc.culture.jewish.moderated)
  • Re: linked list
    ... On 21 Nov 2009 at 14:22, Eric Sosman wrote: ... You too have made an absolutely classic beginner C mistake. ... which will typically be placed in read-only memory. ...
    (comp.lang.c)
  • Re: Why shouldnt a sex offender work on a schools website?
    ... - Governors will have said "She's had to pay the price for a serious ... mistake, but she was a friend and colleague for a long time - let's not ...
    (uk.legal)