[SDL] SDL 2.0: Evaluating API Usability (Long)

[Edward Cullen]

Hello,

I'm a 3rd year Software Engineering undergraduate at University of
Southampton (http://ecs.soton.ac.uk). I also have a part-time
development job with Sony.

As part of my degree, I have to undertake a research project. I have
decided to look at API usability, using SDL as an example.

Background
==========

An API is essentially programmer-centric (whereas an ABI is
implementation-centric). There is a lot of literature stating that 'Good
API design is important', but very little empirical research as to what
constitutes good design.

For example, from the C Std Library, opening a file is done via:

	FILE *fopen(const char *, const char*);

with FILE * returning NULL on error. However, it could just as easily be
written as:

	int fopen(const char*, const char*, FILE *);

With the error code being returned. Alternatively,

	void fopen(const char*, const char*, FILE *);

with any error being placed into a global variable.

Does one of these offer any particular advantage over the others? Does
it depend on what kind of application you're developing etc, etc?

Objective
=========

I am interested in researching what makes a good API, from a
programmer's perspective. I also intend to examine the links between C
and C++ APIs, specifically, is it possible to design a C API in a way
that makes a native C++ API more intuitive or straight-forward.

Hopefully, it will be possible for my results to be fed-back into the
development of SDL 2.0, to make it even easier to use.

Next Step
==========

Following my initial research into the area, I have come here to ask
users of SDL for their views and experiences using SDL.

I am NOT interested in the capabilities of SDL - this is a question for
Sam and Ryan, who, as professional game developers, are in a MUCH better
position to judge what is and is not necessary.

The question I have is what YOU like or don't like about the way APIs
within SDL are presented. What are your pet hates? What makes you go
'wow, that's really easy to use'?

If you would like to participate, please read the 'Legal Bit' at the end
then answer the following questions (remembering to reply to me or CC me):

--------------
START
--------------

First, in order to classify my results, please categorise both your
education AND experience.

--------------
CLASSIFICATION
--------------

EDUCATION - One of:

	- SELF-TAUGHT (No formal programming teaching / qualifications)
 	- NON-DEGREE programming course (E.g. Sun Java Cert or people who had
a small amount of programming as part of a degree, such as Maths,
Physics or Electronic Engineering)
	- DEGREE: More than 1 year of a Computer Science or related (Electronic
Engineers who were TAUGHT a lot of programming as part of their degree
fit this category).

EXPERIENCE - One of:
	- FOR FUN: Amateur/just for fun devs.
	- PART-PROFESSIONAL - professional devs with less than 2 years
full-time experience in a commercial environment. (either inside or
outside games industry).
	- FULL-PROFESSIONAL full-time non-game developer with 2 or more years
experience. (Includes people who have not worked in games for 2 or more
years)
	- GAME DEV professional (full-time) game developer with 2 or more years
experience.

For example, I would be DEGREE, PART-PROFESSIONAL.

--------------
QUESTIONS
--------------

These questions are fairly free-form. Please feel free to be as verbose
as you like, quoting examples, C, C++ or other code (even Lisp or
Prolog!) if you feel it is appropriate.

1. What do you like about the presentation of the SDL APIs? Which tasks
do you find particularly easy, straightforward or simple? Which APIs do
you feel work really well for the task they are intended for?

2. What DON'T you like about the presentation of the SDL APIs? Which
task do you find particularly difficult, awkward or confusing? Which
APIs do you feel make the task more difficult? What are your pet hates?

3. How do you find error handling? What do you like about it? What don't
you like about it? Are there particular examples of error handling in
other APIs that you prefer? Why?

4. If you use / have used SDL with C++, please answer the following:
	a. Do you wrap SDL in C++ class(es)?
		- If not, why not?
		- If so, what difficulties / gotchas have you encountered? Which APIs
have been particularly troublesome?
	b. Have you tried using exceptions in your SDL code? Which approach(es)
have you used? Did you give-up and go back to traditional (C-style)
error handling and if so, why?

5. Any other comments that do not fit the above.


--------------
END
--------------

Legal Bit (Actually REALLY IMPORTANT!)
=========

It is my intention to use any comments made in relation to this post as
part of my research, for which, the copyright will be held by myself
and/or University of Southampton (UK).

Data Protection Act 1998. Any personal data collected will be used
exclusively in connection with this research project. The originating
email address will be stored purely in order to facilitate the collation
of the comments made by an individual (e.g. to remove duplicates) and
for direct email communication by me in order to clarify any comments.
The final published data will not contain any information that can be
used to identify individual contributors.

For the avoidance of doubt, please email your response to me directly
(CC: will be fine). I will take this as your acknowledgement and
confirmation of consent. NOTE: If you fail to do this, I will NOT be
able to use your contribution!

Many, many thanks in advance,

Eddy

Edward Cullen
February 2008