My single counter point. The code almost never explains how or why
something was deleted /out/ of the code because it was Bad.

Don't assume everything in past versions is everything the programmer
wrote in that method. Much of what the programmer learned was
something he tried/failed and threw away, but which a new user might
try /again/ because it was NOT in the code already. All the convenient
searching shortcuts begin to fail if you need to find out how code has
changed over time as one tries to understand it or how not to redo
something bad.

The code also rarely tells you that the code which you may
"understand" actually has code smell, is a /bad/ example, or is an
archaic style of programming. Java may be inconsistent, but so is the
Squeak class library... all the way down.

Sometimes you can't see the forest for the trees.

Cheers,
Darius
[|] Powered and Empowered by Smalltalk