Software craftsmanship: convey intent in your error codes

ENOTSUP stands for “Error – not supported” and it is one of the many error codes defined in the error header file.

I recently learned about this specific error code when reviewing a pull request that my colleague had submitted. His code review contained an outline — a skeleton — of how we envisioned laying out a new control plane process that would allow upcoming dataplane processes to integrate with.

And he kept this initial revision very concise, only defining the signature of the functions and simply returning the error code ENOTSUP.

The advice of returning relevant error codes applies not only to the C programming language, but applies to other languages too, like Python. But instead of error codes, you should instead raise specific Exceptions.

Who cares

So what’s so special about a one liner that returns this specific error code?

Well, he could’ve instead added a comment and simply returned negative one (i.e. -1). That approach would’ve done the job just fine. But what I like about him returning a specific error code is that doing so conveys intent. It breathes meaning into the code. With that one liner, the reader (me and other developers on the team) immediately get a sense that that code will be replaced and filled in in future revisions.

Example

Say you are building a map reduce framework and in your design, you are going to spawn a thread for each of phases (e.g. map, reduce). And let’s also say you are working on this project with a partner, who is responsible for implementing the map part of the system. Leaving them a breadcrumb would be helpful:

int worker_thread_do_map(uint32_t thread_id)
{
    /* implement feature here and return valid error code */
    return -ENOTSUP;
}

int worker_thread_do_reduce(uint32_t thread_id)
{
    return -ENOTSUP;
}

The take away

The take away here is that we, as developers, should try and convey meaning and intent for the reader, the human sitting behind the computer. Cause we’re not just writing for our compiler and computer. We’re writing for our fellow craftsman.