Writing Clear Code: Naming Conventions

      No Comments on Writing Clear Code: Naming Conventions

Writing Clear Code: Naming Conventions

One of the best things you can do for the developer who looks at your code after you (even if that happens to be you again) is to use a consistent and predictable naming convention for your classes and methods.
PHP itself is littered with inconsistently named functions, making it difficult to remember whether you need to call strlen(), strLen() or str_len(). This is, understandably, annoying since even seasoned PHP developers often need to look at a reference to remember less used commands.

You don’t have to be that way.

My personal preferences are capitalized CamelCase for class names and namespaces, and regular CamelCase for method names and variables. I do not prefix any names with anything, especially not with their data or return types (you will sometimes see variables like $strName and methods like iFollowers()). Private and protected variables and methods are handled by PHP and I use a modern IDE, so I don’t prefix those with an underscore (like $_myPrivateVar).

Whether you follow the same guidelines I do or not, if you are not consistent your code will irritate the crap out of the next developer. Since you never know who might be a psychopath or not, you probably shouldn’t try to piss him or her off!

Best Practice: CamelCase is a way of naming things that allows you to show word splits without adding extra characters. An alternative form, CamelCase, makes the first letter lowercase instead.

Finally, it is important to decide on a “voice” for your method names. You may choose to be very specific, including the action along with the noun (typically a get or set prefix), or you might decide to use the existing implied relationship between the object name and method name (ie. using name() for a function that can both get and set a name). For example, if you have a class named User containing information on a user, and you are adding a method that retrieves the user’s full name, you could use getName() or name(). Personally, I use the shorter version, name(), although I illustrate the longer method below. Whichever way you go, be consistent.

<?php
/**
* A sample class to illustrate good naming conventions.
*
* https://datashuffler.org/writing-clear-code/
*
* @package AWPExample
*/
class User {
/**
* The name of this user.
*/
private $name = NULL;

/**
* Retrieves the name of a user.
*
* @return string The name of the current user.
*/
public function getName() {
$return = NULL;
if (TRUE === isset($this->name)) {
$return = $this->name;
}
return $return;
}
}
?>

Remember, underscores have no place in names, classes and namespaces begin with capital letters, and if your class name matches the name of the file containing it, using a PSR-0 autoloader is really, really easy.

You’ll notice a couple of seemingly wasteful things in that method – my use of a $return variable and that I’m checking to see if the class variable has been set before using it. In the first case, I don’t like rewriting things, so if I ever need to add code to munge the data before returning it, I can just insert it. For the second case, checking to see if a class variable is set before using it is simply a safety habit I’ve picked up over the years – there’s no reason not to do it, and you never return an invalid value from the method.

Leave a Reply

Your email address will not be published. Required fields are marked *