This is a question of opinion on API usage, not a direct coding question.

I've got an API. This API calls underlying C functions. The author of the C library changed his mind to remove safety checks on a particular routine (eg: setup()), so that it no longer checks whether that function has been called or not.

In some of my Perl code, I do some due diligence and ensure we call the proper setup() in the right order, and ensure it is only called once.

The reason for the checks in the C code, is if an inexperienced or lazy coder calls the function too many times, it can result in a situation where no more system-wide file handles will be available, essentially, crashing the system.

There are five such setup routines. I'll depict them like this:

use constant {
    RPI_MODE_WPI => 0,
    RPI_MODE_GPIO => 1,
    RPI_MODE_GPIO_SYS => 2,
    RPI_MODE_PHYS => 3,
    RPI_MODE_UNINIT => -1,
};
[download]

Now, in my Perl code, I magically track any time a sub module runs to ensure that an already existing setup hasn't been executed. With the C restriction lifted, I *still* want to do this, but I want to drop support for all but the most-used routine (aka pin mapping scheme), which is GPIO.

In my distribution, I have removed all references for the routines I don't want used anymore in the documentation, but left them in code just in case (there's no legacy issue here, as nobody was really using my code before I made that decision).

My question, is whether from your perspective you'd keep true to the underlying C libraries you're wrapping, or sacrifice some convenience to some users, and make things much, much easier for yourself maintainability wise going forward.

Because this is Perlmonks, here's some code. This is some init code that actually aids in deciding whether a setup routine has been called or not. Yes, there are a lot of if/else stuff, but because I knew I'd approach what I'm asking here someday, I wanted it nice and open and free-flowing.

sub new {
    my ($self, %args) = @_;
    $self = bless {%args}, $self;

    if (! $ENV{NO_BOARD}){
        if (my $scheme = $ENV{RPI_PIN_MODE}){
            # this checks if another application has already run
            # a setup routine

            $self->pin_scheme($scheme);
        }
        else {
            # we default to gpio mode

            if (! defined $self->{setup}) {
                $self->SUPER::setup_gpio();
                $self->pin_scheme(RPI_MODE_GPIO);
            }
            else {
                if ($self->_setup =~ /^w/) {
                    $self->SUPER::setup();
                    $self->pin_scheme(RPI_MODE_WPI);
                }
                elsif ($self->_setup =~ /^g/) {
                    $self->SUPER::setup_gpio();
                    $self->pin_scheme(RPI_MODE_GPIO);
                }
                elsif ($self->_setup =~ /^p/) {
                    $self->SUPER::setup_phys();
                    $self->pin_scheme(RPI_MODE_PHYS);
                }
                elsif ($self->_setup =~ /^W/){
                    $self->pin_scheme(RPI_MODE_WPI);
                }
                else {
                    $self->pin_scheme(RPI_MODE_UNINIT);
                }
            }
        }
        # set the env var so we can catch multiple
        # setup calls properly

        $ENV{RPI_SCHEME} = $self->pin_scheme;
    }
    $self->_fatal_exit;
    return $self;
}
[download]

Removing all of the setup routines less the one I want would make it *tremendously* easier to support going forward maintenance-wise, as well as making things a lot more flexible in the long run. I can still perform the safety check, but a lot of code could be removed, and the checks would become much less aggressive and to put it bluntly, less fraught with potential holes.

I'm thinking remove. What do you think... maintainability or adhering to the underlying API?

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.