From: "Sean E. Russell" Date: 2004-02-13T21:16:13+09:00 Subject: Re: Standard libraries --Boundary-02=_s/LLAPHaob/Bblm Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Content-Disposition: inline By the way, this issue is about a matter of taste, so the debate is somewha= t=20 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=20 library that had good documentation, or (b) never used a large library, or = a=20 large number of libraries in one project. IMO, libraries should be black boxes that perform actions for me. They sho= uld=20 be *allowed* to change their internal implementation. So relying on the=20 source for the library either sets you up for defeat -- you THINK you know= =20 how something is implemented, but the library developer may have changed it= =20 since the last time you looked at it -- or it requires increasing amounts o= f=20 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= =20 APIs. There's a school of belief in the Java community that says that=20 interfaces belong to the user, not the library. Put another way, in an ide= al=20 world, the users of the library define and clearly document the API, and th= e=20 library developer makes sure his/her code conforms to that API. When you=20 adopt this world-view, you start doing things like writing unit tests first= ,=20 writing the API skeleton second, and writing the internal implementation=20 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=20 labor intensive, it shifts the burden of developing knowledge from the=20 developer to the user, and it isn't necessary if you have good API=20 documentation. There is one very real advantage to the way that you work, though. It=20 requires fewer language skills on the part of a developer. Reading the=20 sourcecode is often the only way some of us can figure out how libraries=20 written by people who are not native language speakers work. Still, I'm in= =20 the habit of writing my *own* documentation for those libraries; I have a=20 hard enough time remembering which method call to use for a given task=20 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= =20 would say that the person who wrote the API in the first place is not the=20 same person who uses it later -- even if it is the same entity. =2D-=20 ### SER =20 ### Deutsch|Esperanto|Francaise|Linux|XML|Java|Ruby|Aikido ### http://www.germane-software.com/~ser jabber.com:ser ICQ:83578737=20 ### GPG: http://www.germane-software.com/~ser/Security/ser_public.gpg --Boundary-02=_s/LLAPHaob/Bblm Content-Type: application/pgp-signature Content-Description: signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.3 (GNU/Linux) iD8DBQBALL/sP0KxygnleI8RAho5AKDBbK3QKMSkHkd/dGTc+6PiUbnkWgCgopHp Ssr3U4K3c7/bF+rPSydp1HQ= =2DbW -----END PGP SIGNATURE----- --Boundary-02=_s/LLAPHaob/Bblm--