Achieving Object-Oriented Design in the C Language by using proper function names

Question

I am writing a MISRA compliant code that runs on a microcontroller, and this program must be written in the C language. I would like to design my software according to the object-oriented design. However, the C-language lacks OOP support. Therefore, I decided to create "classes" and "packages" through C-files and Folders, respectively. Currently, all legacy function names were having the following names: <Module_Name>_f_<Function_Name>_<Return type>.

This function naming convention works as long as there is only a single Module. However, if I add SubModules or even SubSubModules, then the function name might get confusing. For example, having Module, Submodule, and a SubSubModule might end up in one the following function names:

1. <Module_Name><SubModule_Name><SubSubModule_Name>_f_<Function_Name>_<Return type>

2. <Module_Name>_<SubModule_Name>_<SubSubModule_Name>_f_<Function_Name>_<Return type>

3. <Module_Name>_f_<SubModule_Name>_<SubSubModule_Name>_<Function_Name>_<Return type>

   ...

What would be a good name for such functions, and their respective C-files? I would like to have a naming convention that one can read and still understand the "class"/"package" structure?

To make it more clear, we can take more concrete example with the following file structure containing Folders and C-files:

Module (Folder)
  - SubModule_1 (Folder)
     - SubSubModule_1_1.c
     - SubSubModule_1_2.c
     - SubSubSubModule_1_2_1.c (Maybe also put in a seperate Sub-Folder?)
     - SubSubSubModule_1_2_2.c (Maybe also put in a seperate Sub-Folder?)
     ...

  - SubModule_n (Folder)
     - SubSubModule_n_1.c
     - SubSubModule_n_2.c
     ...

The above file structure might look like this in an OOP pseudocode:

class Module:
  begin Module;

    # Field Declarations
    SubModule_1 subModule_1_Instance;
    SubModule_2 subModule_2_Instance;
    ...
    # Function declarations
    Module_f_<Function_Name>_<return type>;
    ...

  end Module;


class SubModule_1:
  begin SubModule_1;

    # Field Declarations
    SubSubModule_1_1 subSubModule_1_1_Instance;
    SubSubModule_1_2 subSubModule_1_2_Instance;
    ...
    # Function declarations
    ModuleSubModule1_f_<Function_Name>_<return type>;
    OR 
    Module_SubModule1_f_<Function_Name>_<return type>;
    OR
    Module_f_SubModule1_f_<Function_Name>_<return type>;
    ...

  end SubModule_1;


class SubSubModule_1_1:
  begin SubSubModule_1_1;

    # Function declarations
    ModuleSubModule1SubModuleSubModule11_f_<Function_Name>_<return type>;
    OR 
    Module_SubModule1_SubModule11_f_<Function_Name>_<return type>;
    OR
    Module_f_SubModule1_SubModule11__f_<Function_Name>_<return type>;
    ...

  end SubSubModule_1_1;

So for the SubSubModule_1_1, I might end up with:

1. ModuleSubModule1SubModuleSubModule11_f_<Function_Name>_<return type>;
2. Module_SubModule1_SubModule11_f_<Function_Name>_<return type>;
3. Module_f_SubModule1_SubModule11__f_<Function_Name>_<return type>;

Is there maybe a better way to name those functions? I am looking forward to Your replays/alternatives. Thank you in advance.

Answer 1

Sticking to an OO design is almost always a good idea, but you need to boil down OO to the things that matter. Namely:

• Autonomous objects that only know of their designated purpose and know nothing about unrelated things.

  For example in an embedded system, your SPI driver shouldn't and needn't know anything about the LCD you are using, even though you are communicating with the LCD through SPI.

• Private encapsulation that hides information away to reduce complexity, tight coupling and namespace collisions.

• In some cases, inheritance.

  For example if you are writing a portable HAL that should function the same no matter the underlying microcontroller hardware. (Like for example a SPI driver.)

All of the above OO can be achieved in C and the language directly or indirectly has language support for it. There's misc other concepts like "RAII", which are handy but not necessary. Unfortunately we can't get automatically called constructors/destructors in C, so we have to live with calling them explicitly.

The main thing to concider when doing OO in C (and other languages) is to do it on a file level. The header file should contain the public interface - everything that the caller needs to know, that you would normally have declared public in a language with keyword support. Each header file contains a corresponding .c file containing the private implementation details.

It's a good idea to have a strict naming policy like in your examples, so that the caller knows where a certain function belongs. The functions belonging to the SPI driver spi.h should be named spi_init, spi_transceive and so on, with the source code prefix first.

Not sure if I like the SubSubModule idea though, seems a bit burdensome. Also, in an embedded system there should be just so many cases where you actually need inheritance, it is a bit of a rare beast rather than the main attraction in most programs. Often it can rather be a sign of poor design and over-engineering with far too many abstraction layers. It's also important to never let your inheritance API be set in stone. Don't hesitate to change it later on, when you discover new requirements that weren't considered during the initial design.

Regarding private encapsulation, C supports that through the static keyword. Functions declared static in the .c file are truly private and can't be accessed from other files. It doesn't work quite as well for variables though. You can use static file scope variables as a "poor man's private", that's in fact how it is done most of the time in embedded systems. static variables have some limitations though: they force the object to become a "singleton pattern" with only one instance possible. Which is fine if you only need one instance of the SPI driver, but what if the MCU comes with 5 different SPI peripherals, all behaving identically?

As a side note, static variables aren't thread-safe in larger, multi-process/multi-thread programs. Could become relevant in case of RTOS.

It is however possible to take OO one step further in C, by using the concept known as opaque type / opaque pointers. Examples. This allows you to create multi-instance classes, fully encapsulated, or optionally with some public parts. It can be used to model inheritance and polymorphism, by letting the first object of the inherited class contain a struct instance of its parent. Function pointers enable "virtual" inherited functions, where calling a function through a base class pointer invokes the corresponding function in the caller.

An object declared as opaque through pointers to incomplete type cannot be allocated by the caller, they can only declare pointers to them. From the caller's perspective they work essentially just the same as abstract base classes in C++. You will have to encapsulate the object allocation inside the init function (constructor). This is a bit of a disadvantage in low-end embedded systems, since sanity demands that we don't use malloc there. Instead memory allocation will have to be done through a fixed maximum size static memory pool. Examples: Static allocation of opaque data types

From a MISRA-C perspective, they actually encourage the use of opaque type since MISRA-C:2012 (Dir 4.8).

Do not over-use opaque type though. It makes perfect sense for things like HAL on top of drivers, portable code, protocol handling etc. But not so much for hiding away non-portable, application-specific logic, which doesn't benefit from abstraction layers since you won't be able to re-use or port it anyway.

Overall, program design is highly qualified work. It takes lots of experience to get it done properly. Add too much abstraction and you end up in over-engineered, meta-programming hell. Add too little and you end up in spaghetti-programming, tight-coupling hell.

Answer 2

The concept missing from this discussion is the "this" pointer to have instance-specific data. It's implicit in C++, but must be explicit in C.

For example, in a hypothetical module NSMotionController.c:

typedef struct NSMotionControllerStruct {
   float speed__m_s;
} NSMotionController_t;

float NSMotionController_SpeedGet__m_s(NSMotionController_t const * const this) {
     return this->speed__m_s;
}
bool NSMotionController_Initialize(NSMotionController_t * const this, float const speedCurrent__m_s) {
     this->speed__m_s = speedCurrent__m_s;
     return true;
}

We can use this like so:

int main(int argc, char ** argv) {
    NSMotionController_t motionControllerInstance1;
    NSMotionController_Initialize(motionControllerInstance1, 1.0f);
    NSMotionController_t motionControllerInstance2;
    NSMotionController_Initialize(motionControllerInstance1, 2.0f);
    printf("speed1: %.1f\n", NSMotionController_SpeedGet__m_s(&motionControllerInstance1));
    printf("speed2: %.1f\n", NSMotionController_SpeedGet__m_s(&motionControllerInstance2));
}

As far as naming, I use a two-letter namespace ("NS" above) since C doesn't support namespaces idiomatically. I use the module name, then an underscore to start the method name. I use two underscores to separate a units suffix ("__m_s" above indicates "meters per second").

For polymorphism, you can use function pointers. So, augmenting our example with function pointers:

typedef float (*NSMotionControllerInterface_SpeedGet__m_s_t)(void const * const this);

typedef struct NSMotionControllerStruct {
    NSMotionControllerInterface_SpeedGet__m_s_t SpeedGet__m_s;
    float speed__m_s;
} NSMotionController_t;

float NSMotionController_SpeedGet__m_s(void const * const this) {
    NSMotionController_t const * const motionThis = (NSMotionController_t const *) this;
    return motionThis->speed__m_s;
}
bool NSMotionController_Initialize(NSMotionController_t * const this, float const speedCurrent__m_s) {
    this->SpeedGet__m_s = NSMotionController_SpeedGet__m_s;
    this->speed__m_s = speedCurrent__m_s;
    return true;
}

int main(int argc, char ** argv) {
    NSMotionController_t motionControllerInstance1;
    NSMotionController_Initialize(motionControllerInstance1, 1.0f);
    NSMotionController_t motionControllerInstance2;
    NSMotionController_Initialize(motionControllerInstance1, 2.0f);
    printf("speed1: %.1f\n", motionControllerInstance1.SpeedGet__m_s(&motionControllerInstance1));
    printf("speed2: %.1f\n", motionControllerInstance2.SpeedGet__m_s(&motionControllerInstance2));
}

Rather than using polymorphism on a single function, though, you can gather them up in a struct and pass that to other modules.

typedef float (*NSMotionControllerInterface_SpeedGet__m_s_t)(void const * const this);
typedef bool (*NSMotionControllerInterface_SpeedSet__m_s_t)(void const * const this, float const speedNew__m_s);
typedef struct NSMotionControllerInterfaceStruct {
    NSMotionControllerInterface_SpeedGet__m_s_t SpeedGet__m_s;
    NSMotionControllerInterface_SpeedSet__m_s_t SpeedSet__m_s;
} NSMotionControllerInterface_t;

typedef struct NSMotionControllerStruct {
    NSMotionControllerInterface_t interface;
    float speed__m_s;
} NSMotionController_t;

float NSMotionController_SpeedGet__m_s(void const * const this) {
    NSMotionController_t const * const motionThis = (NSMotionController_t const *) this;
    return motionThis->speed__m_s;
}

bool NSMotionController_SpeedSet__m_s(void const * const this, float const speedNew__m_s) {
    NSMotionController_t const * const motionThis = (NSMotionController_t const *) this;
    motionThis->speed__m_s = speedNew__m_s;
    return true;
}

bool NSMotionController_Initialize(NSMotionController_t * const this, float const speedCurrent__m_s) {
    this->interface.SpeedGet__m_s = NSMotionController_SpeedGet__m_s;
    this->interface.SpeedSet__m_s = NSMotionController_SpeedSet__m_s;
    this->speed__m_s = speedCurrent__m_s;
    return true;
}

int main(int argc, char ** argv) {
    NSMotionController_t motionControllerInstance1;
    NSMotionController_Initialize(motionControllerInstance1, 1.0f);
    NSMotionController_t motionControllerInstance2;
    NSMotionController_Initialize(motionControllerInstance1, 2.0f);

    NSMotionControllerInterface_t * const interface1 = motionControllerInstance1.interface;
    NSMotionControllerInterface_t * const interface2 = motionControllerInstance2.interface;
    printf("speed1: %.1f\n", interface1->SpeedGet__m_s(&interface1));
    printf("speed2: %.1f\n", interface2->SpeedGet__m_s(&interface2));

    interface1->SpeedSet__m_s(&interface1, 5.0f);
    printf("speed1 (faster): %.1f\n", interface1->SpeedGet__m_s(&interface1));

    /* Example of passing abstract interface */
    NSGroundControl_t groundControl;
    NSGroundControl_Initialize(&groundControl, interface1);
}

In short, never use statics when you can avoid it. This will also help unit testing, which I imagine is next (or hopefully first) if you're working in a MISRA environment.