scr usability, languages and apis

[simon wistow <simon@xxxxxxxxxxxxxx>]

I'm learning a new API.

It's an API for progarmming games in Java and is loosely based on Director's
interface.

It was designed by a guy who works here and a couple of days ago he went on
holiday - today I've hit a problem which I can't work out although it may be
something to do with the fact that I'm inheriting from ScrollingTile rather
than ScrollingSprite so that I can implement Solidity.

It occured to me that an API is like an interface and has some of the same
usability problems.

Take Java (or don't acually) : 

http://java.sun.com/j2se/1.4/docs/api/index.html

Java obviously has guide lines. On an object, to set a variable, you do 

$object.setVariable()

and to get it you do

$object.getVariable()

objects that behave similarly should have as similar APIs as possible. In
fact, one of the poitns of OO programming is to let you do this by only
forcing you to overload the methods which have to be different. 

Look, at this example :


        #!/usr/bin/perl -w

        use strict;
        use IO::File;

        my $file = shift;
        my $fh   = IO::File->new($file);
        my $line = <$fh>;
        print $line;

gets a line from file whilst ...

        #!/usr/bin/perl -w 

        use strict;
        use IO::Socket;

        my $server = shift;
        my $fh     = IO::Socket::INET->new($server);
        my $line   = <$fh>;
        print $line;


gets a line from a remote server.

Basically a good API should, where possible be consistent, predictable and
follow the rule of least surprise. 


The API i'm using at the moment doesn't do this - it's a very good and
powerful API but it's not immediatley obvious how things interact, sometimes
because it goes through hoops to remain OO.

I'm having real difficulties getting something to work and sometimes I'll get
something nearly working, try and implement a feature and find that's
impossible to do and have to recode using a different feature entirely, in my
first example the Object Tree goes like :


java.lang.Object
  |
  +--com.bitbull.filmstrip.Sprite
        |
        +--com.bitbull.filmstrip.Tile
        |     |
        |     +--com.bitbull.filmstrip.scrolling.ScrollingTile
        |           |
        |           +--com.bitbull.gameutils.platforms.Solid
        |
        +--com.bitbull.filmstrip.scrolling.ScrollingSprite



The guy who wrote the API told me I should use Solid because my Sprite needed
to have things bounce off it. However I suspect that it won't now scroll
around the world because it's inherited from Tiles which aren't suppsoed to
push the view of the world around. However ScrollingSprite is missing many
methods defined in Solid and ScrollingTile which is irritating despite the
fact that they have similar functionality.


Following on from that a programming language is effectivley an API, I've
bought this up before on london.pm : I happen to think that Perl is a good
language because it's fairly intuitive - it tries to do what you mean and it
follows english paradigms

unless ($foo)

do { $stuff } if ($bar);

open FILE, "file" or die;

my $variable;    # this does not belong to everybody;
local $varibale; # this is only in effect in the local area.


while ($true)
{
}


do
{

} until ($true);


foreach $man (@men)
{
	last if ($false);
	last unless ($false);
}

You get the picture. Most of you code Perl.

On the other hand English itself is a bad language for useability - it isn't
predictable and there many exceptions to the rules and there are lots of
rules, not alway intuitive.

Don't know where I'm heading with this one really, just a core dump.

/shurg/



-- 
:  everything before here is irrelevant