I’m looking for general feedback here from experienced developers.
As always, please do not turn this into a flame war, or I will stop
soliciting feedback.
Thanks!
Here are some proposed conventions for the SDL 1.3 -> 2.0 rewrite:
API conventions:
SDL functions return a boolean value or a pointer value
SDL functions are prefixed with “SDL2_” … “SDL_” ?
SDL functions take a status pointer as the first argument
This status pointer can be 0, but no error information will be saved.
e.g.
bool SDL2_Init(SDL_status *status, Uint32 flags);
SDL_VideoMode *SDL2_FirstVideoMode(SDL_status *status, Uint32 flags);
If a function returns 0 or a NULL pointer, an error code or string
can be retrieved from the status object:
SDL_string *string;
switch (status->code) {
case SDL_OUTOFMEMORY:
/* Perform garbage collection and try again? */
break;
default:
string = SDL2_GetStatusString(status);
ShowMessage(“Operation Failed”, string);
break;
}
SDL_statuscode is an enumerated type that contains as many error
conditions as possible. These are organized into extendable blocks
so that individual drivers can add their own error codes.
Each function prototype will include a documentation section which
contains return value, parameters, and non-driver-specific error
conditions. It will also contain a brief note on thread-safety.
The documentation section is set off by /** so documentation tools
can parse it easily.
Coding conventions:
The SDL code is written in ANSI C using 4 space tabstops and spaces
liberally for code readability:
/**
SDL2_function - this is a useful function to do something
@param status
Standard SDL status information
@param param
A parameter of some type
@return a new object of some type
This function should be used when there is something special to be done.
You should watch out for X, Y, and Z, as they can surprise you.
How much useless documentation can I write for a fictional function?
Thread-safety: This function is completely thread-safe
@see SDL_status
**/
object *
SDL2_function(SDL_status status, int param)
{
/ This comment adds clarity to the code */
if ( internal_function(status) == failure )
handle_failure(status);
else
handle_success();
/*
* Note that C++ style comments are not allowed by some compilers.
* Also, keep the code formatted to 78 characters if possible.
*/
if ( (condition_one() == failure) ||
(condition_two() == failure) ) {
handle_failure(status);
} else {
handle_success();
}
return new_object;
}
What do people think? Good? Bad? Ugly?
Again, this is for constructive feedback, so if you don’t have anything
nice to say about someone’s opinions, don’t say it!
See ya!
-Sam Lantinga, Lead Programmer, Loki Software, Inc.
and HRESULTs are