Question

I remember the old effective approach of studying a new framework. It was always the best way to read a good book on the subject, say MFC. When I tried to skip a lot of material to speed up coding it turned out later that it would be quicker to read the whole book first. There was no good ways to study a framework in small parts. Or at least I did not see them then.

The last years a lot of new things happened: improved search results from Google, programming blogs, much more people involved in Internet discussions, a lot of open source frameworks.

Right now when we write software we much often depend on third-party (usually open source) frameworks/ libraries. And a lot of times we need to know only a small amount of their functionality to use them. It’s just about finding the simplest way of using a small subset of the library without unnecessary pessimizations.

What do you do to study as less as possible of the framework and still use it effectively?

For example, suppose you need to index a set of documents with Lucene. And you need to highlight search snippets. You don’t care about stemmers, storing the index in one file vs. multiple files, fuzzy queries and a lot of other stuff that is going to occupy your brain if you study Lucene in depth.

So what are your strategies, approaches, tricks to save your time?

I will enumerate what I would do, though I feel that my process can be improved.

• Search “lucene tutorial”, “lucene highlight example” and so on. Try to estimate trust score of unofficial articles ( blog posts ) based on publishing date, the number and the tone of the comments. If there is no a definite answer – collect new search keywords and links on the target.
• Search for really quick tutorials/ newbie guides on official site
• Estimate how valuable are javadocs for a newbie. (Read Lucene highlight package summary)
• Search for simple examples that come with a library, related to what you need. ( Study “src/demo/org/apache/lucene/demo”)
• Ask about “simple Lucene search highlighting example” in Lucene mail list. You can get no answer or even get a bad reputation if you ask a silly question. And often you don’t know whether you question is silly because you have not studied the framework in depth.
• Ask it on Stackoverflow or other QA service “could you give me a working example of search keywords highlighting in Lucene”. However this question is very specific and can gain no answers or a bad score.
• Estimate how easy to get the answer from the framework code if it’s open sourced.

What are your study/ search routes? Write them in priority order if possible.

Answer 1

I use a three phase technique for evaluating APIs.

1) Discovery – In this phase I search StackOverflow, CodeProject, Google and Newsgroups with as many different combination of search phrases as possible and add everything that might fit my needs into a huge list.

2) Filter/Sort – For each item I found in my gathering phase I try to find out if it suits my needs. To do this I jump right into the API documentation and make sure it has all of the features I need. The results of this go into a weighted list with the best solutions at the top and all of the cruft filtered out.

3) Prototype – I take the top few contenders and try to do a small implementation hitting all of the important features. Whatever fits the project best here wins. If for some reason an issue comes up with the best choice during implementation, it’s possible to fall back on other implementations.

Of course, a huge number of factors go into choosing the best API for the project. Some important ones:

1. How much will this increase the size of my distribution?
2. How well does the API fit with the style of my existing code?
3. Does it have high quality/any documentation?
4. Is it used by a lot of people?
5. How active is the community?
6. How active is the development team?
7. How responsive is the development team to bug patch requests?
8. Will the development team accept my patches?
9. Can I extend it to fit my needs?
10. How expensive will it be to implement overall?

… And of course many more. It’s all very project dependent.

As to saving time, I would say trying to save too much here will just come back to bite you later. The time put into selecting a good library is at least as important as the time spent implementing it. Also, think down the road, in six months would you rather be happily coding or would you rather be arguing with a xenophobic dev team :). Spending a couple of extra days now doing a thorough evaluation of your choices can save a lot of pain later.