Forums

* Sarah Keating <skeating@caltech.edu> [2008-09-18 18:00] writes:
> Hi Stefan
>
> SH> I am not sure that the proposed solution is sufficient. Even in future
> SH> releases of SBML being it levels or versions. The semantics of each
> SH> element in the document is specified by the default name space of the
> SH> containing document. Starting with this premises I think that it must
> SH> be impossible to create any SBML object without referencing the
> SH> document.
>
> I agree that people should not create objects independent of the document
> - but unfortunately they do :-)

<snip>

> At the moment the ideal way for people to create objects is to use the
> create functions;
> which is achieving what you suggest by referencing the document.

As someone who is new to libSBML and who just wrote some code to convert
models to and from SBML format, I can say that if the intent is for users
to use the create functions instead of the constructors, this is never
expressed anywhere in the documentation that I read. The only advantage
of using the create function that I could see was that I didn't have to
stuff the object into the document later. So when I wanted to skip that
step, I used 'create' and when I wanted to mess with it first, I used a
constructor.

If 'create' really is superior, the docs should say so when describing the
constructors and the 'create' functions (and explain why).


As far as changing the API in general, changing 'void' functions to 'bool'
is transparent and would require no change to existing code... as long as
the code still worked, and didn't suddenly start failing for a reason that
was previously acceptable. If the new code introduces new cases that
might cause functions that used to be guaranteed to work to no longer have
that guarantee, but old code would never invoke those new cases, I see no
problem at all with changing 'void' functions to 'bool' ones.

If some cases used to work that now won't, that's a bit more worrisome.
Perhaps the function could continue to act as it had in the past, but
return failure as well?

Finally, if there were cases that used to fail but never told the user it
failed but now will, that's a definite positive change.


One last thing--traditional C/C++ code tends to return 0 on success, and 1
on failure. This makes it simpler if you later want to add ways to
distinguish between different failure modes, to just add '2', '3', etc.,
and old "if(function())" code will still work. It makes bool functions
more confusing, though; just something to keep in mind.

-Lucian
____________________________________________________________
To manage your libsbml-development list subscription, visit
https://utils.its.caltech.edu/mailman/listinfo/libsbml-development

For a web interface to the libsbml-development mailing list, visit
http://sbml.org/Forums/

For questions or feedback about the libsbml-development list,
contact sbml-team@caltech.edu