[GRASS5] function return values?

[Glynn Clements]

Markus Neteler wrote:

> while looking at the return codes of 5.0, it seems that
> there no standard was followed. To improve things in
> 5.1 we should define some rules (for SUBMITTING) and
> also update code accordingly when moving it to 5.1.
> 
> Suggestion (there will be exceptions):
> 
> error: 0
> success: 1 (this allows a simple if(G_function()) test
>             without comparison).
> 
> Being no expert here, I hope for comments,

That may be confusing; Unix functions which return an integer normally
return -1 for an error, with all non-negative values indicating
success, while functions which return pointers return NULL for error
and non-NULL for success[1].

Similarly, program exit codes are 0 for success and non-zero for
error.

[1] Except for mmap() which, for some bizarre reason, returns
((void *) -1) for error; anything else, including NULL, indicates
success.

To repeat the comment from my last message, unexpected errors should
normally be fatal. Experience suggests that programmers often neglect
to check status returns, so it's best to avoid them where possible.

The main situations where a status return makes sense are:

1. The function normally returns something useful, and you need to
choose a specific error value for the case where a meaningful value
cannot be returned. The error value is normally constrained by the
need to avoid conflicting with normal values (i.e. returning -1 if a
normal value is non-negative).

2. Failure is not uncommon, and the function often doubles up as a
test. E.g. "does object X posess optional value Y, and if so what is
that value?".

As far as is practical, the libraries should handle errors rather than
passing the responsibility onto the program (i.e. onto the
programmer).

It would be worth extending error handling to something more
substantial than G_set_error_routine(). At least an option to push/pop
error handlers, and to nest error handlers; that would provide similar
functionality to C++/C9X exceptions.

ACID-style commit/rollback on output would be nice, but that's
non-trivial.

-- 
Glynn Clements <glynn.clements at virgin.net>