A good API will not only provide easy to use interfaces, but also provide hard to mis-used interfaces. Usually, the later point is the fundamental of the earlier one. Consider you want to write a date class, there are thousands of ways to write it. Let’s see two simple examples:
// A date class which is easy to use but also easy to use wrong.
Date(int month, int day, int year);
// Both are ok, but some european programmer may use it wrong.
// Because european time is dd/mm/yyyy instead of mm/dd/yyyy.
Date d(3, 4, 2000);
Date d(4, 3, 2000);
// Class date which is easy to use and not easy to use wrong.
Let’s see another example, suppose your interface returns a dynamically allocated resource which need to be released after all. The chances are programmers might forget to release it causing leaks. Returning a smart pointer maybe a good idea.
// Not easy to use interface, client has to remember to release the resource
// Better interface returning smart pointer. Resource is released automatically