Since the sample Watson code is downloadable and intended to show how to use these services, I find it odd that you cite "over commenting" as a problem. Comments are a great thing in sample code, especially in code that you can download separately, without docs.
For the jobid example, the stringify is necessary because the jobid returned by the server includes a # symbol. Try the code you suggested and you get the result: "Error: ContextExpansion Error: jobid is in incorrect format."
Re:Watson Services
by colanderman on Wednesday October 08, 2014 @02:35PM
(#8428612)
This is a perfect example of why I don't like to take silly shortcuts based on tenuous assumptions like the GP suggests.
Assumptions, more often than not, (1) change, (2) are understood differently by others, and/or (3) (as in this case) are flat-out wrong. Code that takes "advantage" of such silly assumptions usually (1) are poor examples to coders new to the project, (2) complicate reviewing the code for correctness, and (3) waste brain-time figuring out when they can (and can't) be applied.
Just escape everything that should be, whether you think you know what it is/where it came from or not.
This rampant clumsiness is fairly typical for IBM code samples--doing things manually that should use a popular library, or choosing obscure or IBM-invented libraries for common things. For example, the Java example should really use Jetty or CXF for JAX-RS rather than mucking about with HTTP client calls directly...
http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercl...
To make a simple call with the Java example, you've managed to write 372 lines of code.
Three hundred and seventy two lines.
That's some bad code.
There's nothing I can point at and go, that, that's what's wrong, the whole thing just has a lot of code smells. The 'zZz's (what is that DIY escaping all about?). The multiple http calls that should have been abstracted into one function, but aren't. The over commenting. The api structure requiring you to do 3+ calls. The exponential call back time (this is not a good idea, have fun with weird bugs). That you've made your own json objects. That you've used PUT for a pretty tenuous reason. That you've put all the urls in some config file or something, so the code isn't particularly clear at what it's doing.
The ruby & javascript are more terse because those languages are, but they aren't that much better. It's often silly little things, like this:
Could have been written simply as this: There really is no good reason to use 'querystring.stringify' in that instance, it's not user input. The code's simply over-complicated.The code reads like a sysadmin/amateur/uni professor's code, a scripter rather than a professional programmer's. It's like you don't have a senior dev on the team to cast an eye over it and get rid of the excesses.
The APIs themselves are not bad, as I mentioned there's the slightly tenuous PUT stuff, the only other annoyance I could see is that you'd have to ping it all the time to see if it's ready. I appreciate why, and you've made the right call in the callback vs ping, simply because so often when hacking setting up a callback would be hell.
It's better than a lot, like google or paypal, so it's not all bad.
NB: But now I just found this exploring github:
https://github.com/Watson-Explorer/wex-wdc-integration-sampl...
Which at first glance is better code than the examples on the site? Bit odd.