Object oriented SDK development

If you are someone who is into object oriented SDK development and looking for some best practices on API design, I have got you covered here. I have used C++ as the base to explain the core. OpenCV is one of the frameworks I have come across that does an exceptional job in providing classic and productive APIs in C++. Let's not waste time an quickly jump into the best practices of object oriented API design.

Design easy-to-read API names

First and foremost thing to consider in an object oriented SDK is the API name itself. Your API names should reveal everything. Keeping APIs as small as possible can be a difficult task but that is what you should deliver. The API should do what the name says. Nothing more. Nothing less. 

Write your headers and review it

Before you jump into development, it is important to code what the user wants. To have a crosscheck on that, write a header file(.h or .hpp) containing the public/private functions and data members. In this process, you can eliminate methods and data members that is not needed for the SDK user.

Hide your implementation details

In a closed source SDK where only headers will be given, every single word in your header matters. You would not want to expose any of your implementation details. So hide data members that are not 100% required to be exposed.

In that case where you cant have a data member in private or public, but still you want to access it from another class, you have many options like

• Friend class
• Inheritance
• Pimpl idioms, etc.

A Constructor's workload

Mostly, constructors would be used to initialize the variables. But it is also used to allocate memories and initialize using other functions. The problem with the latter is sometimes when memory allocation fails, constructors cannot return errors. Keeping all these in mind, it is always advised to have a separate method for initialization to allocate memories.

Maintain a standard

When it comes to maintaining your source, there are many places where you should follow standards throughout the code. Listed below are some of them: 

• If you use pointers, use only pointers throughout. If you use references use only references throughout. Bringing both might lead to some confusion.
• Use namespaces along with the function names in all the usages.
• Have a template for prolonging/recursive namespace usages.

Error handling

There are many ways to handle errors if you are a C++ developer. But I like enums. Enums allow you to maintain error messages really well. Have a common numbering pattern to maintain your error messages. 

Getters and setters

Have getters and setters for the private members. In some cases where private variables can only be given read access and not write access, can opt for read-only objects. This is however, a standard practice in object oriented programming.

Meme section has its say on OOPS B-)

I have listed only some of the best practices while developing an object oriented SDK."API designs for C++" by Martin Reddy is a book that explains many more practices in brief with realtime examples is a very useful one to consider. If you feel you have some more best practices, you are free to mention them in the comments section.