[Developers] Interface functions (2)

[Bert Bril]

Hi all,


Getting back to the subject of good interface functions: return values
and const correctness. Subjects that get a lot of attention in C++
books, so the technical side should be known.

Return values can be returned in two ways: via the function's return
value or via references, in the parameter list (or even pointers).
Simple function return values are good for simple values and objects
that can be copied. Often status variables can be returned, or an error
message string that is null on success. The problem is that you can only
return one thing. Thus, if you need to return multiple things, you have
two options: via the parameter list or return a new type - a composed
object. It all depends on preferences and ease-of-use. As long as you
don't lose memory in the process, anything goes.

That doesn't mean anything goes though. Start scratching your head if
you pass more than 3-4 parameters to a function. Especially when you
pass lots of ints and floats: don't. Use the expressive power of objects
and create a new object to pass to the function. That has many
advantages, like:
1) Making awful mistakes in the order of the parameters is impossible
2) Is the new object a useful abstraction by itself? Sets of parameters
can be copied and passed and so forth
3) You can make use of 'Setup' classes

(3) is worth a posting by itself, but look in general.h for the
mDefSetupMemb macro and, for example, uiIo/uibinidsubsel.h for an
example of usage.

Back to return values. Pointer/reference return values behave similar
to parameters: X* means: it's yours. const X* means: it's mine, and it
may be null. X& means I manage it, it can't be null and you can do as
you like with it. With const X& it's mine and you can't change it.


That gets me to const correctness. In order to be able to use the above
'codings', you have to separate const from non-const. Thus, you have to
declare const functions vs non-const in the interface. A function with
'const' at the end of the declaration promises to not change any of its
member variables (other than the ones declared 'mutable'). The
peculiarity here is that within the class itself this is of limited
value - a burden. The return of investment is for the users of your
class, who can use a const function if they obtain a const (ptr or ref
to) object of the type.

That's simple theory from books. Fact is, that we use const manically in
all non-UI classes, but we are rather sloppy in the UI world. This is
because  const-correctness is not very useful for UI work where you'd
have to declare lots and lots of 'mutable' variables, cast away a lot,
and more, for a very limited pay back. Why would one want to pass a
const uiDialog? User interfaces do things and afterwards cease to exist.
Therefore, in UI classes we do as we like ...? Not so. We do honor the
const-ness of the outside world. So a uiXBrowser can take a const X& if
it's only there to show the X and not to change it.


That's it - for now. I guess I've said a lot, there's more but I guess
it's time to stop.


Bert

-- 
-- Bert Bril / OpendTect developer at dGB
-- Nijverheidstraat 11-2, 7511 JM Enschede, The Netherlands
-- mailto:Bert.Bril at opendtect.org , http://opendtect.org
-- Tel: +31 534315155 , Fax: +31 534315104