Do you make safe and unsafe version of your functions or just stick to the safe version? (Embedded System)

Question

let's say you have a function that set an index and then update few variables based on the value stored in the array element which the index is pointing to. Do you check the index to make sure it is in range? (In embedded system environment to be specific Arduino) So far I have made a safe and unsafe version for all functions, is that a good idea? In some of my other codes I noticed that having only safe functions result in checking conditions multiple time as the libraries get larger, so I started to develop both. The safe function checks the condition and call the unsafe function as shown in example below for the case explained above.

Safe version:

bool RcChannelModule::setFactorIndexAndUpdateBoundaries(factorIndex_T factorIndex)
{
    if(factorIndex < N_FACTORS)
    {
        setFactorIndexAndUpdateBoundariesUnsafe(factorIndex);
        return true;
    }

    return false;
}

Unsafe version:

void RcChannelModule::setFactorIndexAndUpdateBoundariesUnsafe(factorIndex_T factorIndex)
{
    setCuurentFactorIndexUnsafe(factorIndex);
    updateOutputBoundaries();
}

If I am doing it wrong fundamentally please let me know why and how I could avoid that. Also I would like to know, generally when you program, do you consider the future user to be a fool or you expect them to follow the minimal documentation provided? (the reason I say minimal is because I do not have the time to write a proper documentation)

void RcChannelModule::setCuurentFactorIndexUnsafe(const factorIndex_T factorIndex)
{
    currentFactorIndex_ = factorIndex;
}

Answer 1

Safety checks, such as array index range checks, null checks, and so on, are intended to catch programming errors. When these checks fail, there is no graceful recovery: the best the program can do is to log what happened, and restart.

Therefore, the only time when these checks become useful is during debugging and testing of your code. C++ provides built-in functionality for dealing with this through asserts, which are kept in the debug versions of the code, but compiled out from the release version:

void RcChannelModule::setFactorIndexAndUpdateBoundariesUnsafe(factorIndex_T factorIndex) {
    assert(factorIndex < N_FACTORS);
    setCuurentFactorIndexUnsafe(factorIndex);
    updateOutputBoundaries();
}

Note: [When you make a library for external use] an argument-checking version of each external function perhaps makes sense, with non-argument-checking implementations of those and all internal-only functions. If you perform argument checking then do it (only) at the boundary between your library and the client code. But it's pointless to offer a choice to your users, for if you want to protect them from usage errors then you cannot rely on them to choose the "safe" versions of your functions. (John Bollinger)

Answer 2

Do you make safe and unsafe version of your functions or just stick to the safe version?

For higher level code, I recommend one version, a safe one.

High level code, with a large set of related functions and data, the combinations of interactions of data and code are not possible to fully check at development time. When an error is detected, the data should be set to indicate an error state. Subsequent use of data within these functions would be aware of the error state.

---

For lowest level -time critical routines, I'd go with @dasblinkenlight answer. Create one source code that compiles 2 ways per the debug and release compiles.

Yet keep in mind @pete becker, it this really likely a performance bottle neck to do a check?

---

With floating-point related routines, use the NaN to help keep track of an unrecoverable error.

---

Lastly, as able, create functions that do not fail and avoid the issue. With many, not all, this only requires small code additions. It often only adds a constant of time performance penalty and not a O(n) penalty.

Example: Consider a function to lop off the first character of a string - in place.

// This work fine as long as s[0] != 0
char *slop_1(char *s) {
  size_t len = strlen(s);         // most work is here
  return memmove(s, s + 1, len);  // and here
}

Instead define the function, and code it, to do nothing when s[0] == 0

char *slop_2(char *s) {
  size_t len = strlen(s);
  if (len > 0) {                // negligible additional work
    memmove(s, s + 1, len);
  }
  return s;
}

---

Similar code can be applied to OP's example. Note that it is "safe", at least within the function. The assert() scheme can still be used to discovery development issues. Yet the released code, without the assert(), still checks the range.

void RcChannelModule::setFactorIndexAndUpdateBoundaries(factorIndex_T factorIndex)
{
    if(factorIndex < N_FACTORS) {
      setFactorIndexAndUpdateBoundariesUnsafe(factorIndex);
    } else {
      assert(1);
    }
}

Answer 3

Since you tagged this Arduino and embedded, you have a very resource-constrained system, one of the crappiest processors still manufactured.

On such a system you cannot afford extra error handling. It is better to properly document what values the parameters passed to the function must have, then leave the checking of this to the caller.

The caller can then either check this in run-time, if needed, or otherwise in compile-time with a static assert. Your function would however not be able to implement it as a static assert, as it can't know if factorIndex is a run-time variable or a compile-time constant.

---

As for "I have no time to write proper documentation", that's nonsense. It takes far less time to document this function than to post this SO question. You don't necessarily have to write an essay in some Word file. You don't necessarily have to use Doxygen or similar.

But you do need to write the bare minimum of documentation: In the header file, document the purpose and expected values of all function parameters in the form of comments. Preferably you should have a coding standard for how to document such functions. A minimal documentation of public API functions in the form of comments is part of your job as programmer. The code is not complete until this is written.