A bad name will kill
Javadoc is quite helpful if you have to deal with a new API. It explains what methods are doing, and the role each class is playing. But let's be honest: How many times have you ever read the javadoc upfront? After studying some basic examples I usually choose classes and methods by name: Hey, this sounds like the functionality I need. Then I check the javadoc to make sure that it actually is what I want. But this requires that names are well chosen... Bad names do not communicate a method's purpose or, even worse, they communicate the wrong intention. So what are the reasons for poor naming? Well, one reason is for sure careless naming. The one who designs an API knows exactly what it does, so, with a certain lack of sense, he won't even recognize that it's badly named. Another reason is refactoring or redesign that changed the intention of a method. Means: the name was wisely choosen in the first place, but after changing the methods semantics, the name has not been ...