Re: Standard libraries

By the way, this issue is about a matter of taste, so the debate is somewhat 
moot.  However, I feel compelled to comment that:

On Friday 13 February 2004 01:14, NAKAMURA, Hiroshi wrote:
> From my experience, for good development, library user
> should read the source instead of per method document
> (and library developer should aware of it).

In my experience, I'd say that this means you've either (a) never used a 
library that had good documentation, or (b) never used a large library, or a 
large number of libraries in one project.

IMO, libraries should be black boxes that perform actions for me.  They should 
be *allowed* to change their internal implementation. So relying on the 
source for the library either sets you up for defeat -- you THINK you know 
how something is implemented, but the library developer may have changed it 
since the last time you looked at it -- or it requires increasing amounts of 
your time to stay up-to-date with the source of the libraries you are using.

When software from different developers(1) interact, they interact through 
APIs.  There's a school of belief in the Java community that says that 
interfaces belong to the user, not the library.  Put another way, in an ideal 
world, the users of the library define and clearly document the API, and the 
library developer makes sure his/her code conforms to that API.  When you 
adopt this world-view, you start doing things like writing unit tests first, 
writing the API skeleton second, and writing the internal implementation 
last.  And you end up with better code and a more stable API.

Your point of view works well for small projects, but it doesn't scale, it is 
labor intensive, it shifts the burden of developing knowledge from the 
developer to the user, and it isn't necessary if you have good API 
documentation.

There is one very real advantage to the way that you work, though.  It 
requires fewer language skills on the part of a developer.  Reading the 
sourcecode is often the only way some of us can figure out how libraries 
written by people who are not native language speakers work.  Still, I'm in 
the habit of writing my *own* documentation for those libraries; I have a 
hard enough time remembering which method call to use for a given task 
without having to re-read the entire sourcecode for the library every time.



(1) When I say "software developers", I also mean a single person.  Taoists 
would say that the person who wrote the API in the first place is not the 
same person who uses it later -- even if it is the same entity.

-- 
### SER   
### Deutsch|Esperanto|Francaise|Linux|XML|Java|Ruby|Aikido
### http://www.germane-software.com/~ser  jabber.com:ser  ICQ:83578737 
### GPG: http://www.germane-software.com/~ser/Security/ser_public.gpg