Naming Conventions FTW

When we start projects, we often follow the naming conventions of our frameworks without even thinking about the “Why?” It almost seems silly to ask until you run into a – hopefully, legacy – codebase that has an incomplete or inconsistent scheme.

Unfortunately, web2project is one of those codebases.

For those just joining us, we forked web2project in late 2007 from dotproject which itself was started in mid 2000. Therefore some of the code goes back nearly 13 years all the way back into the PHP 3 days. Therefore, there’s a little.. cruft. And naming conventions are just one piece.

First, we’ve had a simple Object Relational Mapper (ORM) since the earliest days. It handles our object to database (and back) conversion with no configuration. While there are many arguments for and against ORMs, it works and makes things simple.

Next, we surface those object properties to the form elements on the add/edit screens. It allows us to generate forms, validate the input, and move it along whatever the next step entails. There was nothing particularly unique here.

Where things got interesting was in the rendering (View) layer..

Previously we had a flock of little inconsistencies. There were places where a date field was displayed as a simple date on one screen, a full am/pm datetime on another, and a 24 hour datetime on yet another. In other places, a user’s name was displayed as a username in some places and a proper first and last name on others. While fundamentally, these are low priority issues, it’s annoying and shows a lack of attention to detail that haunted the forums.

So for the v3.0 release, we developed an HTMLHelper to standardize display throughout the system. It works quite simply by passing in the data we want to display along with the name of the field itself. For example, if we were displaying a task end date, it would look something like this:

echo $htmlHelper->createCell(‘task_end_date’, $task_end_date);

The method parses the field name to retrieve the datatype which then determines how the data is displayed. We end up with dates displayed as dates, budgets are displayed as currency, and urls are converted to clickable links. When you pass in a name – like project_name, task_name, etc – it will automatically link to a view of the object. In most cases the proper link is structured as “index.php?m={module}&a=view&{module}_id=n” except where it doesn’t.

Because this is one of the places the naming convention breaks down..

There are a total of total of 12 modules which have ‘name’ properties. Of those, four of them don’t follow the convention for module names, one doesn’t follow the convention for property name, and one has a completely different url pattern to view it. In short, this is a hairy mess. What should be three lines of code without any odd conditional processing turns into fourteen lines of code with twelve conditionals.

And this is one of the simplest places. The complex ones have dozens of lines of code with just as many conditionals.

Naming conventions are ridiculously powerful and useful.. and failing to follow them makes life difficult for everyone coming later.

You can read the entire Naming Convention specification on Github.

Are you interested in API Design? Check out our new book "A Pragmatic Approach to API Design." In it, we cover the basics on why you might need an API, how to get started on modeling your API, and finally some design patterns and anti-patterns to be aware of. Available soon from LeanPub