On Thu, Apr 29, 2004 at 12:23:03PM +0100, Benjamin Geer wrote:
> John Goerzen wrote:
> >I'm looking at java.io right now.  I count no less than 10 interfaces
> >and 50 classes.  Let's say that I want to open up a file for read/write
> >access and be able to seek around in it.  Looking at the class list, I
> >don't know if I want BufferedInputStream, BufferedOutputStream,
> >BufferedReader, BufferedWriter, CharArrayReader, CharArrayWriter,
> >DataInputStream, DataOutputStream, File, FileDescriptor,
> >FileInputStream, FileOutputStream, FileReader, FileWriter, InputStream,
> >InputStreamReader, OutputStream, OutputStreamWriter, RandomAccessFile,
> >Reader, or Writer.  Really, I literally *do not know how to open a
> >simple file*.  I would not call that intuitive.
> 
> You actually have to *read* the documentation, not just glance at the 
> class names. :)  That's to be expected with a powerful API.  Once you 
> understand the key concepts governing the design of the API, it makes 
> sense, it and becomes intuitive to select the classes you need.  I tried 
> to point out these concepts in the message you replied to.

You shouldn't need to read a boatload of documentation just to read a
file, even one encoded in UTF-8.  Especially one encoded in UTF-8,
since in the future most files on Unix will be encoded that way.

Think of an API as like a user interface.  It's a UI for programmers
to use.

Good user interface design does *not* require you to read manuals to
find out how to use it (excepting very special cases like airplanes,
surgical equipment, etc.).  If you designed a website or a computer
program that required you to read a manual before you could use it, no
one would ever use it.  Simple fact.  Don't make an API which needs
you to read manuals to do a trivial operation like slurping in a UTF-8
file.

Here's how you read in and parse a CSV file using my OCaml CSV library:

  let csv = Csv.load csvfile in

('csv' is a list of list of strings).  I deliberately chose to make
the common case this simple because it's the common case and people
shouldn't have to remember much to use it.

> To read a file containing UTF-8 text, one line at a time:
> 
> BufferedReader in =
>     new BufferedReader
>     (new InputStreamReader
>      (new FileInputStream(filename), "UTF8"));

This example really reflects all that's wrong in Java.  Thankfully I
don't have to do Java programming any more - I got out of that job as
soon as I could.

Rich.

-- 
Richard Jones. http://www.annexia.org/ http://www.j-london.com/
Merjis Ltd. http://www.merjis.com/ - improving website return on investment
http://www.YouUnlimited.co.uk/ - management courses

-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners