Why method naming is important

Illustration of poor naming from animation Adventures of Captain Wrongel (pun in Russian)

Method naming is important. We all know that. That’s written in books, we get naming suggestions in every pull request. This makes us watch our naming more closely, and we get better in naming our methods: getThis(), setThat(). You know.

But it’s not only about clear names. It’s more about how the name really reflects what code is doing, how it supports better readability and understanding of the code without documentation.

And it really works both ways: when checking a method, you should check whether it really does the thing it was named for. Because if it’s not — that might be a flag that the code is poorly structured.

Let’s check an example.

Say we have an entity that represents some configuration setting a user might store. Let it also support versioning, so that some setting changes could be reverted to a previous state. The original settings entity is stored in a separate table (config_settings). Different previous versions of it - in another one (config_settings_history). Overall it corresponds to the 4th type of slowly changing dimension data management approach.

All that is backed up with database schema like the following:

Snippet 1: Database schema

Now, let’s say that we have a requirement for entity deletion. But since it is versioned, the latest entity from version history should be made as to actual upon deletion. Unless allEntriesShouldBeDeletedis specified. In this case, both actual and history entities should be deleted. Everything is pretty straightforward.

This is implemented with the following code:

Snippet 2: Initial implementation

I’d like you to take a minute and study the code. Do you have any questions regarding the implementation? Or maybe regarding method naming?

Ok, let’s check it together now.

Here we have deleteConfigSettings that checks the flag and deletes the entity and clears the history for it if the flag is true.

Or it calls the helper method setNewestEntryFromHistoryAsActual, which sets the entity from history as actual, if the flag is set to false. First, it checks whether any history entry is there at all. If not - it just deletes the actual. Well, alright, makes sense so far.

Wait, deletes the actual? I thought we were talking about setting stuff judging from the method name? That should be a flag for you. So remember this one. Moreover, we now have a code duplication, since there is delete called in different parts of the same workflow.

Else block is alright, though. We set the one from history as current and delete from history. That's what method name suggests and that's what should be there. But the first part really belongs to the parent method.

Let’s refactor these methods a little for method naming reflect more precisely what the method is actually doing:

Snippet 3: Refactoring

Alright, the method setNewestEntryFromHistoryAsActual is correct now and adequate to the name. Also, note the signature. It now takes only ConfigSettingsHistoryEntity as a parameter. It's a good sign we are moving in the right direction.

The method deleteConfigSettings is now, well … more ugly. But, that's for the best! We can now see what's wrong with it. Remember those deleting logic duplication? Well, it's still there, but now it’s more obvious.

We have two deletes: in case areAllEntriesShouldBeDeleted is set to true, and in case there no history entries. But there is no point for these to be in separate parts of the code. But the first one also deletes all history entries, we can't simply merge them in one place.

Wait, why is that? Shouldn’t history entries be deleted automatically already if we wish to delete current one?

Well, they are not deleted now because there are no cascades in the database! Totally missed that:

Snippet 4: No cascades

That’s a good way to get a bug you’ll be hunting for hours. If you think about it — there is no point in keeping history entries once the original one is removed, since they are not referenced from anywhere.

Moreover, if some new entry will be created it will be inhering the history of a previously deleted one. Here, you have a bug. Just forget this separate call somewhere in the code.

Let’s add cascade:

Snippet 5: Cascades

And some more refactoring to our methods:

Snippet 6: Final implementation

Well much better, isn’t it? The delete is only one and only in one place. setNewestEntryFromHistoryAsActual does the promised and we found and fixed an issue in our database schema, which was hidden by poor method naming.

The beauty of if that the code now reads very well:

if all entries deletion flag is set or there are no history entries — delete entry,
otherwise — set latest as current

Try reading the initial code. Well, it’s gonna be messy and very long, and you’ll forget what was in the beginning by the end! And that is basically how you would read the code when need to add changes and anything.

You should always remember: the easier it’s read — the easier it’s maintained.

So the idea behind all this.

Poor method names or implementation that doesn’t stick to the name can make the code less readable or even uncover some serious design flaws and should be considered as a major code smell.

How to check whether method naming is right:

• method name describes exactly what method does
• method only does one thing and has simple name(methods sharing more than one function tend to have complex names like deleteEntryAndSetLatestFromHistory)
• method parameters should not be excessive (setLatestFromHistory should not require current one, timestamp or anything, as it should not operate on them)
• try reading your method out load (when nobody is there, of course), it should come out as normal sentence describing the method logic

As always I would be very glad for any feedback or questions! Please feel free to post them right here in the replies or in personal notes.

Other Useful Resources for learning Java you may like

10 Best Practices to remember while naming variables in your program
10 Things Java Programmer Should Learn in 2019
10 Free Courses to Learn Java from Scratch
10 Books to Learn Java in Depth
10 Tools Every Java Developer Should Know
10 Reasons to Learn Java Programming languages
10 Frameworks Java and Web Developer should learn in 2019
10 Tips to become a better Java Developer in 2019
Top 5 Java Frameworks to Learn in 2019
10 Testing Libraries Every Java Developer Should Know

Top 10 Java Online Courses for Beginners