Let’s be honest: there is a lot of really bad code out there. The tsunami of bad code cannot be overcome by the relative handful of gurus who have mastered code craftsmanship. Books become outdated, and the examples in training courses are so contrived that they can’t be applied to real work situations. Developers these days need byte-sized chunks of wisdom using real-world examples that can be applied to the work they are doing today.
To that end the No Bugs Project is joining forces with Keep Calm and Refactor to create a series of posts with practical, real-life examples of bad code, and how to make it better. Refactoring tools and techniques will be applied to real open-source code to show what real clean-up looks like. The GitHub projects will be there with the code and the change history for all to see how it’s done and follow along.
The first topic will be one of the hardest: Naming. We name packages, classes, methods, and variables, among other things. We will discuss all of these. There’s more to naming than most developers think. Otherwise, their code would be much easier to understand!
An unclear package name can be very confusing. A classic example of this is when you need to find a class or service that is associated with a business requirement. Enterprise projects are complex and developers can spend a lot of time searching for the correct class or service that they want to reuse.
What is wrong with having a bad package name?
A practical example of having unclear names on packages might be:
A new developer comes in your team and he needs to reuse a service to search for discount promotions but this service is in a very generic package called payment.
Imagine that there are more than 15 classes in the payment package. Also, the searchPromoDiscount method is inside a PaymentService class. How can they find it now? Even developers who have been working on the code base much longer won’t know where it is.
What will they have to do then? They will have to use brute force and look through each class and each method one at a time. Every time someone needs to extend this functionality, they will need to go through the same time-wasting exercise. This is a very strong indicator that the code is not good.
Use the Single Responsibility Principle. Create a unique package for each important business requirement. If the Promo Discount is an important business requirement the best one can do is to create a package called, promo discount. That’s it! By following this discipline, all developers will be able to quickly and easily find the classes they are looking for. But remember that it’s necessary to use good names in classes too.
In object-oriented programming, objects are nouns and methods are verbs. Java as a language was designed to be object-oriented. It has developed some functional capabilities, but remains, in the main object-oriented.
It is important to remember that classes are object definitions. Class names should be nouns. If a class name is a verb, it can be very confusing and is a strong indicator of Bad Code. For example, the venerable FindBugs code analysis tool has a class named “Analyze“. What would an Analyze do? It would…analyze something, of course! In looking at the code the methods of the class perform various specific analyses on the code being inspected. So this is a sort of utility class for analyses. A name like “AnalysisUtilities” would be much clearer. Or maybe even just “Analysis“. But the name “Analyze” is a code smell that makes us wonder what it’s for and what we might find inside. Does it contain one or many analyses? If it’s one, is it a static method in the constructor? Maybe it’s an interface that all the various analysis functions are based on. So many things it could be! A name like “AnalysisUtilities” lets us know exactly what to expect.
Another class naming code smell is to change a verb into a noun. This is usually done by adding “er” to the end of a verb. Something like, “TaskRunner” or “Manager”. This is usually an indication of a developer who knew that classes have to be nouns, but since it only has one, or very few similar methods, they just named it after the method. “It runs the selected task, so I’ll just call it ‘TaskRunner’ and the method will be ‘run'”. A less confusing name would be “Task” and it would still have a “run” method. And it would be much more clear to the next developer who has to look at this code. If you find yourself ending a class name with “er” you may be just getting lazy about the name. Good naming takes extra thought and effort, but that few extra seconds of thought will pay back many hours of confusion from those who have to read this code later.
When naming packages, classes, methods, or variables, consider that these are the names that likely will be used for the life of the application. These names will be discussed in meetings and design sessions monthly, weekly, and sometimes even daily. With that in mind, you should name packages/classes/methods/variables as if they were your firstborn child.
Join the discussion and if there is a specific tool or technique or discipline you would like to learn more about, leave a comment. If you have a piece of code that needs some work – and it’s permitted to be published online – contact Rafael at the No Bugs Project or Scott at Keep Calm and Refactor. We love to squash bugs out of that old, gnarly code!