Name Convetion

Name Convention – A better approach

If your read my previous post about Clean Code, this will fit right along.

This post is about choosing the right and correctly variables/classes or functions names for your code.
Picking up a good name convention in some cases eliminates the need for comments, because your code will explain what’s going on.

So, how do you choose a good variable naming convention ?

Use self-explanatory names

Look at the following code

foreach ($x as $c) {
	if($c->engine == 0) {
		...
	}
}

Now look at this

foreach ($cars as $car) {
	if($car->engine == ENGINE_BROKEN) {
		...
	}
}

The problem with the first is that, it lacks context, you may know what $x or $c contain, but a year from now or some other developer has no clue just by looking at that. You you see the “engine” there, but is it a boat, a plane, no…it’s wrongly used variables names (no pun intended).

In the second one, it’s obviously more verbose, but if your read it to yourself it’s almost english-readable. You can easily read it like “For each car in my cars check if the engine is broken and something about it” while the first one it’s pretty much cryptic.

So, avoid using single letters in your classes and code. They should only exists in very small pieces for code/functions.

Avoid long variables names

I see this countless times, sometimes developers get carried and create long useless, painful to read variables names.

Bad:

$firstNameWithCapitalizedWord = something();

$emailForUserWhoForgotHisPassword = something();

Better:

$firstName = something();

$userEmail = something();

The first example is horrific and I see it every now and then, long variable names are very hard to read and sometimes they include gratuitous context. You should never have more than three words as variable name.

Don’t use prepended junk

This is a classic mistake when it comes to variables.
you should never use prepended names for your variables. Here’s an example:

$Foo_firstName = ...

$MyCompany_totalEmployees = ...

Imagine this all over the code and it can be quite lame. Some will argue that this helps them identify code they created when working on somebody else’s code.
I say this doesn’t help on anything, as developers we have better tools to identify our code from the rest without having to add junk to our code.

Also, this is pretty bad if you are using and IDE, imagine typing $my and hit tab, all the variables will be listed, while if you used $firstName it should be a lot fast for the IDE and you.

Don’t be funny

Sometimes we are in a good mood and we reflect that in our code, but don’t be the funny variable name guy

$OMFG = 12;
$ForeverAlone = true;

While this may be funny to read, it’s not really that funny when a year from now you don’t have a clue what this does, worse, your co-works have no clue what it represents.

Don’t be redundant

This one is also a classic mistake.

$stringName = "Joe Doe"; // It's a name, so obviously it will be a string, not a boolean duh!
$intAge = 28; // Ages are always numeric..no need for int there
$peopleArray = array(); // This one is even more self explanatory 

I’m using PHP here, since it’s a dynamic language it’s easier to follow on this trap.

One thought on “Name Convention – A better approach

  1. Permalink  ⋅ Reply

    Matthew

    January 19, 2013 at 3:06am

    If I may add another one to the list… I see way too many people do things like

    $delete = unlink(‘some_file.txt’);

    if(!$delete)
    {
    $log->error();
    }

    This can simply be if(!unlink($some_file.txt’)… When I caught myself doing this before I manage to reduce quite a bit of space.

Leave a Reply

Your email will not be published. Name and Email fields are required.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>