Using Software Interfaces

In the past I briefly touched on the topic of public interfaces and interface stability.

One of the unfortunate side effects of the power of web search engines (e.g. google) today is that nobody looks for product details in the product documentation anymore. After all it is so much easier to google for the relevant info. I do it all the time, works great.

So what is unfortunate about it?

Most Sun products go to great lengths to document their public interfaces and to make sure they don't break over time - that's why most Sun products have such an excellent track record of backward compatibility. But when I say "document their public interfaces" I mean, of course, document them in the official product documentation which can be found at http://docs.sun.com.

When you find details of interface behavior elsewhere - not on docs.sun.com - then you need to check the corresponding manuals on docs.sun.com to validate the info. If it's not there or there is any difference, then you cannot depend on that behavior!

Sadly, I see this too often. We'll get a customer query on something that "broke". When we get the details, turns out they are doing something that never should have worked and when we check the documentation there is nothing there that suggests it should work. When we ask how they ended up with that usage, the answer is "We googled for it and found some website by some guy who tried it and it seemed to work".

It's a terrible position to be in because we never want to tell a customer they have to undo their work. Sometimes we can accomodate the unexpected usage. But other times, there really is no other answer than "It can't work, you'll have to fix your code".

So my message on this Friday evening is... "some website by some guy who tried it" is not official Sun documentation. You really must go to http://docs.sun.com for that!

(I won't categorically state that depending on private interfaces is always wrong. It can be useful at times! As long as everyone involved understands that this is the case and understands that the behavior may change at any time for any reason (or even no reason at all) and is happy to accept the inherent instability of doing so... then, maybe it can be ok, in limited, non-production, cases.)

(P.S. Yes, I realize I just wrote 9 paragraphs on what is usually expressed by a single four letter word ("RTFM!").. but I think it is important enough to expand on the topic a bit ;-)


Comments:

Post a Comment:
Comments are closed for this entry.
About

jyri

Search

Top Tags
Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today