Upcoming Events

CodeWorks 2009
Joind.in: real time feedback from real people

Welcome

This is not the home of dotProject or web2project. It is the home of CaseySoftware, LLC. Any dotProject support questions should be referred to their support forums.

Ads

Text Link Ads
Useful Naming Conventions
Tags: 
Date: 8 December, 2008 - 10:19

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...


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

But don't touch script names

I agree, but we have to keep some fun in the actual names of our scripts. Two examples come to mind:

1) I once wrote a billing script that replaced an employee. I named the script after the employee. It was my virtual "rachel" (or whoever the person was).

2) I wrote an invoicing system that pulled in data from various sources. It was necessarily complex and the script came to be called billing kung-fu.

Different things!

I agree and happen to think it's important for scripts/apps to have meaningful names.  And realistically, the name of the app is not going to have any appreciable benefit to understanding what the internals of it do.

This past summer I was working on an application that would analyze previous investment strategies and attempt to figure out new ones... charting the course, so I choose the name Magellan.

script and variable names

Very much agree that function/method names can never be descriptive enough. Last project I had to clean up, the previous programmer had a hatred for vowels and a love for abbreviations that made no sense or were ambiguous.

Last fun script name I made was called 'bobbyTables'. meaningful variable names are important but sometimes it's too tempting to have a little fun with them.
for example:
$bootstrap=new Custom_Bootstrap();
or
$bs=new Custom_Bootstrap();

i think both are readable and memorable but only one is amusing.

USe active voice for booleans/tests

When I write a function that returns a boolean true/false, i try to prefix it with is or has, ie isOpen or hasMembers. If its a class method, I omit the noun to avoid redundancy.

ie:
$Project->isOpen();

versus

$Project->isOpenProject();

I also would recommend using complete words instead of trying to get the whole function/variable name to be less than 8-12 chars. Readibility suffers when developers use $prjObj to indicate a "project" object.

heh, never really thought

heh, never really thought about such specifics in function naming, but when I think about it, most of the names I've used for functions lately would fit into your naming scheme.

Naming

That naming system sounds like something that came out of the CMM world. I hate vague non-descriptive function and variable names. But I hate rigid naming standards even more.

We should use sensible names and active voice when possible. To avoid overloading, we should be using namespaces. When calling a method in a class, I think of the class itself as part of the identifier, so $Project->isOpen() is a sensible name. I can see verbAdjectiveNounStructure becoming unwieldy or bastardized into an unholy monster like what happened to Hungarian notation.

Of course, it easier to blame the programmers than weak specs or insane schedules dictated by non-programmers.

Good Point

Without some thought, naming conventions can become a nasty, unweildly beast that causes everyone headaches.  I hadn't thought about the name of the (instance of the) class being a part of the function call.  And as long as your variable names are useful they could easily be part of the convention.

Many companies have

Many companies have programmers which no habits or poor habits. The developers seem to name variables how they feel it. What is making me laugh all the time is when I come across variable names related to animals : like "cat", "dog", "foo", "beef". After reading lots of code you start wondering how close the guy was from animals.

Post new comment

The content of this field is kept private and will not be shown publicly.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <br> <img> <p> <blockquote> <strike>
  • Lines and paragraphs break automatically.

More information about formatting options