Subject: Comments in code (was RE: business case for mechanized documentation)
From: "Anderson, Kelly" <>
Date: Fri, 14 Apr 2006 17:06:09 -0600

 Fri, 14 Apr 2006 17:06:09 -0600
> > int HashTableSize = 13;  /* should be prime */
> > 
> > You *don't* want this:
> > 
> >     for (i = 0; i < HashTableSizeWhichShouldBePrime; i++)
> I would propose this:
> private int APrimeNumber = 13;
> int HashTableSize = APrimeNumber;

I asked about this on the TDD list... got a lot of interesting answers.
Some of the best were:

- Make a test that tests that the number is actually prime. (Good
- Wrap the int in a class that is named for prime numbers, and may
contain prime constants.
	as in: int HashTableSize = PrimeNumbers.Thirteen;
- self-descriptive code has emergent results that comments simply can't
- Map map = new HashMap(nextHigherPrime(12));

Bill Caputo really answered it best when he said, "The key point here
though (at least in terms of the smart-alecky response you received to
your idea) is that only by asking the question "what's better than a
comment here?" would one even *begin* to explore the alternatives listed
in this thread. That, IMHO is precisely why XP (and more specifically
TDD) is catching on: the fact that these practices encourage us to
challenge good-enough solutions to find better, simpler, more
intention-revealing solutions instead (TDD does this at the code level,
XP at the project/product level)."

Well stated Bill.


E-Mail messages may contain viruses, worms, or other malicious code. By reading the
message and opening any attachments, the recipient accepts full responsibility for taking
protective action against such code. Sender is not liable for any loss or damage arising
from this message.

The information in this e-mail is confidential and may be legally privileged. It is
intended solely for the addressee(s). Access to this e-mail by anyone else is unauthorized.