far less stressful than naming your child
Introduction
This article will deal with proper naming. I cannot stress enough how important and consequential this point is! Before scarying your pants of, let’s have some fun.
The Problem with this problem
So many times I scrolled through my MainView class finding Buttons called btn1, btn2 and btn3 in search for the button which executes my login() method. The very first user interface builder I used automatically named his items. So why spend the time and doing it by myself, right? Another good or rather bad example I see on a regular basis are methods like write(String src, String dest). This exact beautiful line of s*?# , ehm code, I actually saw in a project I wrote about a year ago. You can imagine that it was rather frustrating to find out that src was supposed to be the absolute filepath and dest the name the file should have after the write method renamed the file. Finding that out took me some time and nerves! Bad naming causes confusion and makes the code way less readable.
Refactoring baby
First thing I did was refactor this method to renameFile(String sourcePath, String newBasename). I bet next time I see this method it will not scare my pants of and will tell me immediatly what it does! This basically is the goal you want to achive with proper naming. Make sure you will understand your code on a single glimpse even after years. Unfortunately I can not present you a step by step program on how to get the best names human nature has ever seen, but I can give you a little guideline which might help you.
- Follow conventions and guidelines
The most easy advise I can give is to use naming conventions or guidelines and use them correctly. Every programming language has it’s own conventions of how naming should be so that another programmer on the other side of the planet could read and understand your code. Always use the right conventions. An experienced java developer might punch you in the face if your method is called GetHTMLFilebyURL(String src). - Avoid disinformation
The variable Map userlist will definitely let you wonder if the author was sober or not. Naming a variable with the suffix …list while the variable actually being a Map causes confusion. I am not saying that you should avoid using suffixes like …list or …map. But make sure that the variable types are corresponding to their names like Map usermap and List userlist. An easier way would be to drop the suffix and just name it users. This way it does not cause confusion whether it is a Map, a List or an Array. - Reveal intentions
A variable List list basically tells you nothing about the content of the list. List lastnames might do a better job. Even more so does int elapsedTimeInDays than int d. The method used above is a very great example of not saying anything at all. write(String src, String dest) is like the worst kind of not beeing descriptive at all. By putting a little more effort in choosing more descriptive names we reveal a much better intention of what we might want to say with our names. renameFile(String sourcePath, String newBasename) literally tells me that it takes the source path of a file and replaces it’s name with the new basename. - Be consistent
Imagine you have two classes talking to the database. A UserHandler class with a create(User user) and a delete(String userId) method. On first sight it is fairly easy to understand that the create() method creates a new User in the database and delete() deletes it. Your second class now is OrderService with methods add(Order order) and remove(String orderId). You might now wonder if create() is in some sort different from add(), or if they do the exact same thing. And if so, why do they have different names. Likewise for the delete() and remove() methods. To prevent this confusion, make sure to only have one method name in all classes for the same action performed. Same goes for classes. Stay consistent by naming your classes for example UserDatabaseService and OrderDatabaseService and your methods create() and delete(). - Don’t get to fancy
On the other hand try not to be be to exaggerated since checkIfAllLettersAreCapitalInLastnames(List lastnamesThatMightNotBeCapitalized) is not really more understandable than isAllCapitalized(List lastnames). - Use associations
A programmer who is familiar with the Decorator design pattern will immediately get an idea of what the class EmailDecorator does without even looking at one single line of code within the class. Same goes for the above mentioned usermap. You clearly expect the map to be a map. If your working group decided to use the suffix …Handler for all their database operation classes then use it to. Use names that everybody else uses.
What have we learned?
Basically we now know how easy it is to prevent ourselves from digging our own graves by simply using proper naming. Be as descrpitive as possible without getting to fancy. This might sound very simple, but let me tell you something. It is not! By putting just a tiny bit more effort in naming your classes, methods and variables you will save yourself an incredible amount of time and stress in the long run!