Funny quote

[Sasha Pachev]

> On Thu, May 01, 2003 at 04:10:53PM -0600, Sasha Pachev wrote:
>> Source code is the ultimate documentation.
> 
>Not funny in the least.

> Maybe not funny,  but indeed true. No matter how  much the documentation
> says that a  piece of software will  do something, the best  way to know
> for sure is to look at the code. :-)

There is definitely a lot of truth to that statement. Many times I have found 
the source itself easier to read that the comments around it. Other times, 
the source has not been as transparant as I would wish it to be. Not sure if 
this was because I was too dense to understand it, or because it was not 
meant to be understood. Other times I have looked at the code for a long 
period of time not understanding much, and then all of a sudden I had a 
perfect understanding of how everything works.

I must admit that my standard sequence of understanding a product is first 
run a test case, then look at the source, if that does not make it clear, run 
more test cases, if that stlll does not help, run it in a debugger, under 
strace, or simply adding some diagnostic messages, and then, if things are 
still fuzzy, read the documentation. Not a very good sequence if the software 
is used to guide bombs to their targets, but works quite well for me in 
situations where failure is harm-free.

I suppose different people have different skills, talents and abilities, and 
therefore different documentation preferences. Some would like to have a 
picture. Others want an essay explaining how it all works, while there are a 
few who would much rather see some more or less clearly written code. To say 
"the code is the ultimate documentation" is somewhat like saying "didn't I 
tell you this in plain English?" to a mostly non-English speaking audience.

-- 
Sasha Pachev
Create online surveys at http://www.surveypro.com/