The Tip Of The Iceberg

Whenever your writing software you should be thinking about the user and don't forget the user can be another developer. Every class you write is eventually going be used by someone else, either another developer at your company or someone externally if your writing an SDK or library.

With this in mind you should be designing the class to best suit the needs of those users. One of the things to keep in mind to achieve this should be to limit what those users need to understand, this might be limiting the numbers of API calls they need to make or keeping the concept count to a minimum.

I look at this as reducing the surface area of code the user is exposed to, let them only have to deal with the tip of the iceberg. So what are the benefits of keeping this surface area small to the user.

• The bigger the surface area of code I'm exposed to the greater the chance that any change you make is going to affect me.
• Every concept I have to learn to use your code is a barrier to entry. This means it might take me longer to figure out how to use your code and increases the likelihood I'll make a mistake or misuse your API.
• The smaller the footprint of your code the easier it is for me to mock it out when I come to testing my code, your helping me maintain the quality of my code. 

So if we agree keeping the surface area small is a good thing how do we achieve it.

I've Seen This One Before

As you develop your code try and solve similar problems in the same way, if you use the observer pattern to monitor one aspect of your system then use it in all these situations.

When you use multiple techniques to achieve the same goal its forcing the user to adapt, this takes time and pushes the inconsistency into their code.

Consistency gives the user confidence they understand how there supposed to use your code and their speed in using it will increase.

Looks Great....What Is It?

As much as possible try and use standard solutions to common problems. As we become experienced developers we develop a keen eye for well known design patterns, when you use these patterns your presenting the user with a fast lane to being able to integrate with your code.

When you get creative in these situations your creating extra and unfamiliar concepts for the user to learn.

A user of your code should never be asking the questions "How does this code work?", "How have they implemented this?". Deriving answers to these questions that shouldn't exist is wasting time before your code and mine is integrated.

It Didn't Look Like That Before

Once you have defined how your code works don't make a change unless it clearly benefits the user, public APIs are not for changing.

A user will soon get fearful and angry if you pull the rug out from under them with every release, force them to learn new concepts, integrate with new APIs or fix broken integrations with existing APIs.

When a user integrates with your code they should only see enough of the iceberg to enable them to take advantage of what your offering. They shouldn't have to understand the whole machine just learn how to drive it, every time you make a change to this aspect think about the brain of your user and try not to exercise it too much.