Keep it Simple, Stupid!

Have a special API function just for that use-case, with just the 2–3 parameters that the user really needs to supply..For the most advanced users (those who weren’t afraid to actually go and read your documentaion), supply more complex, but powerful API functions, that can be used to really squeeze that functionality out of your code.Naming matters — To achieve the task of being self-explanatory, your function and parameter names should be really really obvious..If the user COULD misunderstand what you meant for this parameter to be, they WILL definitely misunderstand it and place the wrong value in it..With your luck, it will be the exact value that will make your system crash unexpectedly in production..To avoid such catastrophes, you should name your functions and parameters with meaningful names, and avoid ambiguous naming.Be Consistent — If you do something one way somewhere in your API, don’t do the same thing in another way somewhere else..The user will excpect everything to work the same throughout your API..That goes for naming (don’t name things differently in different places!), and also for style (don’t use status codes in one function, and exceptions in another…)Basically, we can sum the above advices in simple terms: Design your API as if your 5 year old son, or 87 year old grandma will have to use it..If it won’t be simple and easy, they just won’t use it..And if they HAVE to use it, they will forever hate you for making them get up from their keyboard and go read your boring documentation…. More details

Leave a Reply