Quite the title, eh?
This post is about API, services, or interfaces that are obscure and require 'internal' knowledge to use successfully. What do I mean?
Object result = doIt(object1);
There are two specific scenarios that I think about for obscure AI/services:
This happens only in API's where the language allows passing of references and the objects passed are non-immutable.
System.out.println(bean1.getValue()); //prints "default"
System.out.println(bean1.getValue()); //prints "modified"
By simply calling a method, the objects you passed to it have changed. This may not be an expected result and you have to know that is the intent of the API...i.e., you have to have carnal knowledge about it. And, do not be fooled if it has a return-type, it can still modify the reference!
Carnal returns requires significant pre-knowledge on how to handle the return.
Object o = getMyStuff();
In the above example, you have no idea what is supposed to be returned, and even worse, it may return one of, say, five different types of objects that do not have common interfaces. Although you can check/reflect (pending language) what the actual object-type is supposed to be. Horrible!!!
String result = changeThis(String rawdata);
This example is almost as bad - the returned String content may be something unexpected: i.e., could be XML, could be comma-delimited string, could be raw java/perl/php code that you are expected to run. This can be allieviated easily with documentation AND specifying in the method signature the expected result:
String result = changeThisToXML(String rawdata); //returns XML
Just trying to share some awareness that just because you found a neat/cool way to pull something off, other people (or you using someone elses) may run into obscure or unexpected results related to Carnal Knowledge requirements. There are indeed times when you can only do it a certain way, just rememer to document and modify your method signatures to make it as clear as possible -- you never know, 5 years later you might have to use your own API/Service!
NEW: I recently learned that, surprisingly, there is functionality when writing Stored Procedures to *change* the fields in the resultset based on parameters passed in...and that people do this!! Exact same problem.