I spent the better part of a day trying to figure out why a clearly documented API call didn't work as advertised. It turns out that the library uses the same class name, but in a different package, for an implementation class with different methods, and Eclipse auto-completed to that package. That's reprehensible. Don't entrap your fellow programmers like that!
Several of my graduate students are working on a rather mundane problem, to get code grading results into the learning management systems that exist on many college campuses. Those systems work fine with multiple choice and fill-in-the-blank questions, but they don't have great extension points for scenarios such as “fill in this code and have the autograder run it”.
The principal extension point that they do provide is called “Learning Tools Interoperability” or LTI, and it's your typical heavyweight design-by-committee thing. And nobody ever thought of a homework assignment where students were asked to complete multiple coding problems.
So, we are developing plumbing, using the generally admirable Play framework. I had to do something with JSON-P, so that a run-of-the-mill educational app that didn't want to buy into the byzantine complexity of LTI could still be useful.
Play has a perfectly nice helper class to do the JSON-P thing. So I called it. And got a bizarre error message.
I tried adding the Scala library to the project. I tried compiling with the
activator tool that Play provides for those people who prefer to work with
vim instead of Eclipse. That gave me a different (and, as it turned out, more accurate) error message, that there was no
jsonp method with a string and a
It took me the better part of a day to figure it out.
I shouldn't have imported
play.api.libs.Jsonp class is an undocumented internal implementation class that doesn't have a
jsonp method, but only methods with ugly names such as
Of course, I didn't consciously import
play.api.libs.Jsonp. I just typed
Jsonp and accepted the first suggestion that Eclipse gave me. I had no idea that there was more than one
Jsonp class. The API docs list just one.
This particular programmer was familiar with the use of the underscore to uglify Java method names (
writeableOf_Jsonp). So why not put it to work with class names as well? I would have never accepted autocompletion to
Ugly package names aren't the answer. I've seen lots of source files with bizarre imports such as
where someone hit Ctrl+Space to autocomplete
Providing pretty names in implementation packages is a terrible, terrible thing to do to your fellow programmers. DO NOT do this! If you have an implementation class that you don't expect users to use, give it an ugly name, such as
Jsonp_Impl. DO NOT rely on package names to separate user-level classes from implementation classes. Not everyone programs in
vim, and when one uses an IDE, autocompletion of package names is a deeply ingrained habit.