Shared publicly  - 
 
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!
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.
6
Ivan Wooll's profile photoCay Horstmann's profile photoMargaret Leber's profile photo
4 comments
 
when one uses an IDE, autocompletion of package names is a deeply ingrained habit

A bad one. IDEA shows you all the matching include possibilities and makes you pick one. 
 
Next time it happens, you will remember this. Some lessons are cheaper to learn than others.
 
+Margaret Leber Eclipse shows you all of them too. When one is a knucklehead in a hurry, like me, in Eclipse or IntelliJ, and the first choice seems reasonable, that's the one that probably gets picked. That's entirely my point. If you write a class that isn't a reasonable choice for API users, just give it a name that makes this clear. It's a cheap thrill. Just append Impl or whatever. Don't rely on package names.
 
I think it's an impractical requirement to expect a library writer to name his classes in anticipation of what might be going on in some other package he's never even heard of. Class names are intended to convey meaning to users of a package, not to ward off the lost and wandering.

"Don't rely on package names" is not really helpful advice; separating namespaces is what package names are for, and if you're going to ignore them, you get what you deserve. 

Especially in this case, where Play has created the play.api subpackage specifically for the purpose of containing the Play API.

"Impl" sucks, and is ugly too. Really. 
Add a comment...