Embedded software developers have grown used to working at the lowest, nitty-gritty hardware level within a microcontroller based system. Twiddling and manipulating bits and bytes is what embedded software developers were born to do. The embedded software industry is changing and that change is requiring developers to start working at higher levels of abstraction which requires designing and creating APIs (application programming interfaces) that allow software to be reused. Let’s examine seven tips for developing great API’s.
1. Make it an Iterative Process
When designing an API or a HAL (hardware abstraction layer), don’t assume everything is going to go right the first time. There is no such thing as one API to rule them all and expecting to create such an API, especially on a single try, is a setup for failure. Instead, start with a draft API with the expectation that it will change slightly in future iterations. Usually over the course of three or four projects, the API will stabilize to the point where further changes are minor to non-existent.
2. Examine More than One Microcontroller Datasheet
If the plan is to create an API that can be used across multiple microcontroller vendors, developers must look at more than a single microcontroller datasheet. Developers should examine the same peripheral for multiple microcontrollers and make a list for all the common and uncommon features. The common features should be rolled up into the API since they are undoubtedly industry standard features while the uncommon features can be implemented in an API extension only if those features are required.
3. Use No More than 10 Interfaces Per Module
The human mind can only consistently remember approximately 10 to 12 pieces of information that belong together. Developers should aim to keep their API’s with no more than approximately 10 interfaces. Expanding well beyond this number will make it difficult to remember the calls and can also make the interface look complex and may even obfuscate understanding. Find ways to refactor interfaces by using control and configuration structures.
4. Test Pre-Conditions and Post-Conditions
A great API implementation will not assume that the calling function or application has done everything it is supposed in order for the function to work correctly. Developers should use assertions within the API to test that all pre-conditions are met and even to test post-conditions to ensure that the API has successfully performed its function. Don’t assume, as many developers do, that everything has been set up correctly and will execute properly. Design and implement the interface defensively.
5. Logical Naming Conventions
A great API will have logical naming conventions that allow developers to easily recognize and recall the API interfaces. Using cryptic letters at the front of API’s will often make developers scratch their heads and question what that symbol meant. Be explicit in the naming convention and follow best practice recommendations such as starting the naming convention from the general and working toward the specific.
6. Provide a Method for Extending the Interface
The goal is to create a great clean interface that is easy to understand