Java API hell

[IHateMyJob2004]

We are currently using a hellish API for Java. It is poorly documented so we are constantly having lessons learned with the API.

To start, we are developing in Eclipse.

The root problem is that we are doing all sorts of discovery on an API and everything is tribal knowledge right now. Al knows this, Bob knows that. And a year later, Al knew this and has a vague recollection of it .... yadda. I can't wait for these people with tribal knowledge to leave (one is a contractor).

To be clear, the Javadoc, if it exists on this API is horrible. And even when it is not, trial and error is often required to truly understand it. And to make matters worse, new engineers on the project have to learn everything others have already learned. And sometimes they end up solving things differently. Sometimes better, sometimes worse. (I'll refrain from discussing all the damned wheel reinvention that is probably occurring)

There are ways to handle this.

Option A: Create a Proxy project that wraps the classes of the API. It sounds daunting but should work most of the time.

Option B: Word Document or similar.

Option C: Open source project that handles this situation. I have no recommendations.

Option D : Whatever thoughts people here have.

 

[purbeast0]

personally i would go with option A. it would create a clean interface and you could use code completion and have the docs right there when looking at the code completion.

keeping external documents like a word doc would just get out of date quickly imo. those types of things are much harder to maintain, plus they are binary so you can't really have multiple people making changes to it then merge them all back together as easily as you can with code.

and damn ... eclipse. i'd quit the job. i can see why your name is what it is. why are they forcing you to use eclipse?

 

[Markbnj]

I don't know if I like the idea of a wrapper project to solve documentation issues. That locks you into maintaining both the wrapper and the docs yourself as their API presumably will undergo some changes over time.

Aside from obvious things like just maintaining an internal wiki with notes for each entry point, what about capturing what you know in a layer of tests? Each test would essentially document what the entry point in the API does, and it would give you a useful check on new versions. You do still have to maintain this going forward, of course, but I feel like it would be more useful than a wrapper.

 

[Cogman]

Sucks. I've been in the same boat with hellish api's (*cough*SmartGWT*cough*). We didn't really come up with a solution, basically the API was bad enough that you just had to learn it through pain, suffering, and looking at previous developer's source code. We had trainings and some internal wiki docs to show how to use it, but those quickly got out of date and weren't really all that helpful in the long run.

A wrapper API might help. At the point of doing that, depending on the complexity of the problem the API is solving, I might consider slowly transitioning off of the library and writing your own.

 

[DaveSimmons]

Tests sounds good. Capture the knowledge of how each API call is supposed to work in a test, including any quirks and weirdness.

If someone changes API code in a way that breaks the test either it tells you the change breaks code elsewhere that depends on the specific undocumented behavior, or that your understanding of the API call is incorrect.

Once you have the skeleton and a few sample tests. each tribesperson could be assigned a herd of API calls to lead to the test harvest.

A wrapper API might help. At the point of doing that, depending on the complexity of the problem the API is solving, I might consider slowly transitioning off of the library and writing your own.

This could work too, especially if you are only using a subset of a large library. The wrapper splits out the parts that you need to know, and packages them in ways that shows how and why you want to use them.

We're using a large open-source framework at work and it's still evolving. I've considered suggesting we fork, freeze and look at replacing or at least simplifying their code so that the changes stop forcing us to update our code for their changes. Rip out all the parts we don't need, only look for patches to merge when a bug affects our use.

 

[KB]

I would do a wrapper class as you suggested. Get each person with tribal knowledge to write the code they know best and document that tribal knowledge in code comments of the wrapper class.

 

[paperwastage]

To start, we are developing in Eclipse.

A) switch to intellij, which has a built-in decompiler (you need to check if you're violating the license of the jar though.. decompiler might give you a better sense if what the API is trying to do), and intellij is a lot better

B) if that API does not change often (and break things), write the wrapper code, and write the proper javadocs for that wrapper code

 

[smackababy]

All I can say is, I understand why you hate your job. =(

I'd avoid the wrapper classes at all cost. I'd also try and convince everyone to move off the API itself, if possible. Any time maintenance in sections is done, remove the API and do what you can yourself (or switch to a new, well documented one).

 

[bogomips]

Had the same issue (more than once) with a huge vendor API. Bad docs, and odd things happen in the API. Only way out is to decompile the code, figure it out, and either document it to write your own high-level objects to interact with the API, and leave the intricacies and gotchas to these impl objs to manage.

Pretty sure any major vendor supplied API will be against decompiling, but as long as you one do it do understand and the API better and not disclose it...

Different decompilers give different results.
Try http://www.neshkov.com/dj.html

 

[Mr.IncrediblyBored]

All I can say is, I understand why you hate your job. =(

I'd avoid the wrapper classes at all cost. I'd also try and convince everyone to move off the API itself, if possible. Any time maintenance in sections is done, remove the API and do what you can yourself (or switch to a new, well documented one).

A wrapper / proxy layer has its advantages. We have our own persistence layer between our business logic and Hibernate. The server code only touches our adapted classes. Should make replacing it with another ORM down the road easier.

 

[sze5003]

Anyway you can use structure 101 to model out the api and then document it yourself in a way you see fit? If it's a third party system see if you can rip it apart and create some interfaces that interact with the api so its easier to use. It will be a pain but should be helpful for the future.