Java API hell

Sep 29, 2004
18,656
67
91
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.
 
Last edited:
 

purbeast0

No Lifer
Sep 13, 2001
53,544
6,368
126
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

Elite Member <br>Moderator Emeritus
Moderator
Sep 16, 2005
15,682
14
81
www.markbetz.net
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

Lifer
Sep 19, 2000
10,284
138
106
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

Elite Member
Aug 12, 2001
40,730
670
126
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.
 
Last edited:

KB

Diamond Member
Nov 8, 1999
5,406
389
126
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

Golden Member
May 25, 2010
1,848
2
76
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

Lifer
Oct 30, 2008
27,024
79
86
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

Junior Member
May 26, 2015
3
0
0
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
 
Jun 18, 2000
11,197
769
126
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.
 
Last edited:

sze5003

Lifer
Aug 18, 2012
14,304
675
126
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.