Rationale for enable/disable function v.s. change_state?

Question

I am implementing a driver for an accelerometer where I have to implement functions such as enable/disable low-power mode.

I can either write:

lis2dh12_low_power_enable();
lis2dh12_low_power_disable();

or:

lis2dh12_low_power_change_state(boolean_t enable);

The former solution is generally more readable, but it may creates extra code such as in this specific case:

void foo(boolean_t status) {
    if (status)
        lis2dh12_low_power_enable();
    else
        lis2dh12_low_power_disable();
}

Is there any rationale (MISRA like rules) for implementing such typical enable / disable functions?

Answer 1

I'd go for implementing lis2dh12_low_power_change_state(boolean_t enable); as is and define the two others as macros around it, like:

#define lis2dh12_low_power_enable() lis2dh12_low_power_change_state(1)

---

BTW: boolean_t isn't C. Since C99 it's either the built-in type _Bool or the macro bool from stdbool.h.

Even more the suffix _t is reserved by POSIX for future types.

Answer 2

This is fairly subjective. I can share my experience, but I can't list any formal sources. MISRA-C for example, does not concern itself with program design and efficiency.

In my experience, a function of the format lis2dh12_low_power_change_state(boolean_t enable); is generally preferred. You get one function less to keep track of and it reduces code size a tiny bit.

But more importantly, cases like your example with if-else, creates a branch, which leads to less effective code on many systems. Since functions like these are often just wrappers around volatile register access. And because of the volatile, the compiler may not necessarily be able to optimize away the branch.

In addition, the caller might have to keep track of if "the thing" is enabled or disabled, so there is often a boolean in the caller as well. It is then more convenient for the caller just to pass this variable on to your driver, rather than having to write an if-else.