The Forgotten Side of Consistency

Consistency is a subject in which I often find myself. Consistent coding styles, development standards, and common libraries and frameworks can help a team of developers work as a single entity. If all functions are indented the same and all variables are given a similar capitalization convention, it becomes easier to rapidly scan through code. When you aren't wondering what scope you are in, you can focus on figuring out what is happening.

However, there is one piece of consistency that far too often gets overlooked - function and variables should be named in accordance with what they do, and all functions that are similar in nature should be named in a consistent pattern.

For instance, I recently worked on an install script whereby a PHP script processes and XML document and modifies a MySQL database to match what is shown in the XML document. In this script, I had no less than six functions that converted an XML node into a PHP array for later processing.

These functions had names such as "ProcessTables", "ConvertFields", "ConfigureKeys", "GetRecordsConfig". These names are all quite different, yet they apply to functions that are all the same. This is bad practice for one simple reason - when someone who is unfamiliar with your code looks at it, you have hindered their ability to quickly figure out what is happening. With that in mind, don't forget that if you haven't worked on a script for a few months, it might as well have been written by someone else.

Here are a handful of tips to help you with consistent function naming:

1. Always do pseudocode prior to writing any actual code. A hasty developer is a bad developer. The sooner you start writing, the longer it will take. There are a million reasons why you should pre-plan your code, but to add onto that lengthy list, it makes it a lot easier to set up function naming conventions.
2. Write an incredibly generic description of what each function does. All of those functions I listed above do the same thing - convert an xml node to an array. The node they work on and how they do their conversion may change, but at their core, they just convert an xml node to an array. When I have a list of my functions, I can go back and give each one a generic description and see which functions essentially do the same thing.
3. Set up a naming convention based on it's generic description. Once you have broken all of the functions down into categories based on description, you can set up a naming convention that will be used for each one. For instance, for all of my functions that convert an xml node to an array, I set up the convention of 'Convert*******Xml' and simply slipped in the description of the node. 'ProcessTables' became 'ConvertTablesXml' and 'ConfigureKeys' became 'ConvertKeysXml'.
4. Create a legend in the comments. Once you have set up a naming convention, it is a good idea to mark off a section in the comments that lists the convention and where each one applies. This will help you later on if you need to add more functions and need a reminder of what the convention is.
   
5. Stick to the convention. The work doesn't stop once the initial development is completed. If you go back to the script and have to make additions, be sure you continue to follow this convention. By using a convention on only half the code, you are only doing half of what you should be doing.