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 into the dark days of PHP 3. Therefore, there’s a little.. cruft. And naming conventions are just one piece.
Regardless, there are some major benefits that come along with using proper (or at least consistent) naming conventions:
- First, we’ve had a simple Object Relational Mapper (ORM) since the earliest days. It handles our object to database (and back) conversion with almost no configuration. While there are many arguments for and against ORMs, it works and makes things simple. In our case, we can add a field to the database, add it to the object, and finally the proper add/edit view and voila. It should just work. In fact, by using our configurable list views, you can add it to the proper lists entirely via the web interface.
- 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 display inconsistencies. There were places where a date field was shown as a simple date on one screen, as a full am/pm datetime on another, and as a 24 hour datetime on yet another. Formatting for user’s name versus username was just as bad. While fundamentally, these issues don’t affect the core logic of the system, they demonstrate a lack of diligence and attention to detail. Besides, the number of bug reports we got on these were ridiculous.
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 wanted to display a project’s end date, it would look something like this:
$htmlHelper->createCell('project_end_date', $project_end_date);
whereas if we displayed a task date time, it would look like this:
$htmlHelper->createCell('task_end_datetime', $task_end_datetime);
The method parses the field name to retrieve the datatype which is usually 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. This makes self-configuring templates start with reasonable defaults. Of course, you can still customize them but that’s your problem, not ours.
Unfortunately, there is one place 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.
