Useful Naming Conventions

In my regular web wanderings recently, I found a great post entitled "The 7 Worst Verbs Programmers Use In Function Calls" and couldn't help but be reminded of a system that I worked on a few years ago.  The core function of the system was named – no kidding – "doStuff".  Everything in the application led towards that, used it, and then did other things as a result.

There are lots of reasons this is a bad function name…

First, there's the obvious one: it doesn't mean anything. "do" doesn't tell you whether it's uploading, downloading, processing, saving, deleting, updating, or anything else.  It's an empty word.  You don't "do", you "do something".

Second, when people use words like "Stuff" or "Something" or "Anything", it is worse not not meaning anything.  Odds are you don't have a class called "Stuff" or "Something".  Intead of saying nothing, you've actually just taken meaning away from what you do have.

Finally, it's trivially simple to name things usefully.  How much time/thought does ittake to look at what your function is doing and simply describe it in a few words?

My naming convention is pretty straightforward, it is as follows:

verbAdjectiveNounStructure – with Structure and Adjective as optional parts

For verbs, I stick to action verbs: save, delete, notify, update, or generate.  Once in a while, I use "process" but only to specifically refer to queues or work backlogs.

For nouns, I use the class or object being interacted with.  In web2project, this is often Tasks or Projects.  If it's Javascript interacting with the page, it might be body or table.  The point is that the code clearly describes the object it's interacting with.

The structure is optional because it's unique to the situation.  A listing screen might request a List or an Array.  One of the core functions used in the Project List for web2project is simply getProjectList.  It doesn't modify the underlying data, just the representation of the data.

The adjectives are something else entirely.  They are used as modifiers to the noun.  Something as simple as getOpenProjects might be easily implemented with a getProjects and a switch parameter, but this tends to generate methods which require quite a bit of understanding of the underlying data and/or structure of the object… not necessarily something you want to encourage. By having more explicit and specific functions, you can completely wrap and hide the implementation from the code using it. Isn't that one of the points of OO?

Of course, you might have different naming conventions in mind.  Yours might even be better.  As long as they add or improve understanding, you're on the right track…