Boost logo

Boost :

From: Stefan Seefeld (stefan_at_[hidden])
Date: 2019-05-30 00:05:57

On 2019-05-29 7:15 a.m., Mateusz Loskot wrote:

> Hi,
> Miral and I, we have been brainstorming on what would be a clear yet
> optimal interface for the thresholding, on Gitter and comments at
> This made me think the issue of interface design for new algorithms is
> more general,
> not just specific to the thresholding. I think it may be worth to set
> some common
> guidelines, to tune ourselves w.r.t. interface design in the direction
> that may be
> preferred in GIL.

While I think I understand your concern (and mostly agree), I'm not sure
it's useful or even possible to provide general guidelines. Designing
good APIs is hard, requires domain knowledge and almost always involves
judgment calls.

But we can try... :-)

> ### Problem Example
> For instance, OpenCV takes approach of single function to 'kill'em
> all', i.e.
> cv::threshold, that takes multiple parameters where combination of
> values and
> flags is significant
> In this approach documentation is crucial to explain what combination
> is valid,
> when `maxval` is used (e.g. with THRESH_BINARY) and when ignored.

Yeah, I agree this is not a good design. :-)

For once, the abstraction seems more harm- than useful. In addition to
the special-casing of what parameter combinations are valid, I'd reason
that some of the functions are in fact doing something else. For
example, I'm having a hard time understanding the concept behind the
"INV" variants. Shouldn't that be a separate operation ? Why is
inversion mixed into the thresholding to begin with ? Is that such a
common combination ?

Sometimes the rationale to combine multiple "variants" into a single
call is that the implementations share a lot of code. In that case it
might be better to put a common _impl function into some `detail`
namespace and then call that from different frontend functions with
suitable parameters.

A different point is about runtime- vs. compile-time parameters. Both
are possible, and which to choose may depend on typical usage, as well
as implementation techniques.

I agree with you that for the example you chose, distinct functions will
actually make the API more readable.

(And for the record: I also agree that the mailing list is a better fit
for such design discussions than a gitter or other channel)



       ...ich hab' noch einen Koffer in Berlin...

Boost list run by Boost-Gil-Owners