OS Framework Selection: How To Examine An API
OS Framework Selection: How To Examine An API
How can you select the right framework amongst an ocean of possibilities?
Join the DZone community and get the full member experience.Join For Free
Thousands of new open-source frameworks are flooding the market with no end in sight. Partly from grassroots open-source movements, and partly from the IT giants who commoditize their software.
But how to select the right framework amongst an ocean of possibilities?
Frameworks Are Sticky
Smart developers realize that adding a framework is easy, but removing it again later is nearly impossible. Frameworks that enter your codebase, stay in. If one doesn't work well, or just gets obsolete, you're stuck with it. Better investigate before you add something.
So, how to get to the best choice for you? Here are some tips and tricks.
What Makes Selection Hard?
Part of framework selection is processing candidates as fast as possible, and only investigate candidates that are worth your time. For some use cases, there are hundreds of possible options to consider.
You want the one that's best for you. It is tempting to choose the biggest and most successful framework in the world. But it might be a very poor fit for your use case and your situation.
You might choose a very hip one that is growing fast. But two years later, you might be stuck with a formerly-über-hip platform that didn't make it to world domination and got abandoned.
How to Select Frameworks in General
First, you must decide and understand very well what you are looking for. What is the concrete everyday actual real problem you want to solve? What's the problem behind the problem? And the problem behind that one? Iterate this: The better you understand your high-level problem, the more it helps to make decisions.
Make a list of things you absolutely cannot do without, your must-haves, and stick to that list during selection. Ignore nice-to-haves. They distract.
Without a must-have list, you'll run into hundreds of frameworks with super nice goodies. It's easy to wander off into a land of endless possibilities, you'll get nowhere. You'll process a lot of unnecessary information, which drains your energy fast. So focus on what you need.
Also, without a must-haves list, it is tempting to run into a framework that you like by a gut feeling, and then its strongpoints become your selection criteria. I hope you see that this is like setting a trap for yourself.
Shortlist and Dismiss List
Only make a shortlist and a dismiss list. Only frameworks that have all the must-have properties belong on the shortlist. At the first missing must-have, do not waste another second on that framework. Put it on the dismiss list mercilessly, note the dismiss reason. Do not investigate it for compensating upsides.
Are you left with no candidates? Or too many candidates? Don't solve it with awarding points to features or deciding on nice-to-haves instead. It is better to reevaluate your must-haves. You have seen many frameworks by now, you have learned, you know better what you need. Some must-haves turn out to be non-essential. Some nice-to-haves may turn out critical for success.
A very fast way to judge a framework is to investigate its API.
How to Investigate APIs
It seems too deep and detailed to start with the API, but it's not. The API of a framework is like the table of contents in a book: A good API summarizes the story of the framework.
Compare Your Problem to Their API
Click through APIs of the framework and a few code examples to see what it really does, and how they do it. Do these API calls seem to solve your problem? You don't need to go through everything, just a few samples here and there are enough. If it's not meant for what you want, it will show: off to the dismiss list, on to the next candidate.
Scan the API
Then, scan the API from a low level to a high level. In good documentation, the low-level calls are at the end of the index, so start there and work your way back up.
Low-level calls give a much better idea of the kind of system you're really looking at, and what technology this thing was founded on. It is much easier to understand the high-level calls and how you will be using them, once you have seen the low-level ones.
You sampled the API documentation or parts that drew your attention. Think of how it came across. All your team members will have to invest time in learning how to use this.
Things to look for:
API is shoddy
The API documentation is shoddy or cryptic
The framework is meant for something completely different
Solution hardly overlaps your problem
Beats around the bush regarding some highly coveted feature
Joining the community seems to prevail over solving the problem
Requires to use a whole bunch of extra software that you don't need and don't want
Shoddy API Naming
When names do not really cover what a function does, it's a bad omen. Often, shoddy function names stem from an earlier use case, which later evolved in a different direction. But now, the world uses it so they can't do a renaming round without breaking compatibility.
Perhaps developers didn't think long about naming and structure at all, and therefore, they painted themselves in a corner with haphazard naming, and now the appropriate names are "occupied" by something else. Likewise, inconsistent naming of parameters of API calls is bad news too.
In a well-designed API, an architect will have forced the organization into a round of consistent naming and structuring before it was released to the world.
Shoddy API Documentation
If it already looks like a bit clumsy at first sight, be sure it's going to be a disaster in real use. Multiple times I had to work with APIs that were just a maze of ±600 functions, sorted alphabetically, without any "getting started" type of explanation. Off to the dismiss list.
"If You Know, You Know" Documentation
Documentation as observed in Unix
man pages and official R language documentation is extremely compact and quickly jumps from plain basics to extremely complex and advanced examples, bragging about its power. Such documentation is great if you already know how it works. But you and your co-workers don't, so it's hard for everyone. Off to the dismiss list.
Description That Repeats the Function Name
A variant of the above is descriptions like this:
bool DeletePSQEntryFromFFFHierarchy (object entry, object hierarchy)
Deletes PSQ Entry from the FFF hierarchy. Casts
Which, understandably, leaves you wondering what PSQ and FFF are, and therefore, what this FFF hierarchy is to begin with. Documentation that offers no clues, pointers, or context is very hard to use. It will be new to you and all your team members and everyone must search like crazy to piece information together. Off to the dismiss list.
APIs for Kung-Fu Masters
A special category to be careful with is the ultra-clean, ultra-high-abstraction level frameworks. The C++ world has some scary examples. Experienced developers like you may think it's fantastic, but if less-experienced developers can't get their heads around it, it won't be a success. Off to you-know-where.
Effects of Poorly Named and Poorly Documented APIs
- Each developer wastes time making the same jungle discovery expeditions and getting lost
- Developers who will read it will misunderstand it and do it wrong
- Developers who don't read will search-copy-and-modify wrong code from each other, multiplying wrong code all over the codebase
- Developers avoid using the framework at all and make up reasons to not use it
- Knowledge monopolization: Adoption stays limited to specialists who get overloaded, leading to an inflexible organization
This time waste is multiplied by the number of developers using the framework. Likewise, time saved by good documentation is also multiplied by the number of developers.
What Should You See Instead?
API: A clear structure that "screams architecture" and clearly explains what this thing is for, where it belongs, and how it's used.
Documentation: Crystal-clear index, tells it like it is, plain language, specific purpose, instructions on how to use it, with simple usage examples. Clear separation of basics and advanced use. Each subject has plenty of hyperlinks to related subjects. There are "getting started" chapters, and chapters that tell what the underlying concepts are.
When investigating frameworks for selection, investigate the API first.
Investigating the API of a framework is a very quick way to investigate its quality, usability, principles, and potential matches for your projects. This gives a quick and deep insight that simplistic "hello world" and "getting started" tutorials cannot provide.
Stay tuned for our next installment where we look at how to spot immature frameworks!
Opinions expressed by DZone contributors are their own.