Previous Article in this Series
Coding guidelines and best practices
Naming Conventions for Files
File names should be descriptive, so it becomes clear what the script or view does just by looking at the name. When more than one word is required, the two words in the file name should be connected by an underscore.
For example, a script which allows the user to edit his/her profile could be called profile.php. If the user profile has more than one page and those are processed with different scripts, then they could be called personal_profile.php, basic_profile.php, etc. (or profile_personal.php, profile_basic.php, etc). This will allow the programmer to find easily all the profile related modules where files are sorted by name. It is not a good practice to call it profile1.php, profile2.php. If someone else has to work on your code, it will be very difficult for them to understand.
Also, apply the following rules:
- Use only small letters for naming files
- For the modules that belong to the administration panel, start the file name with “a_”
- Corresponding modules for the user end should have the same name without the “a_” prefix
- Templates (views) must have .html extension. They should be named exactly like the module which includes them (unless the module includes more than one template)
- When a module is included within another module, its name must start with “include_”
When working with a third party framework, the naming conventions of that framework should be used. If the framework does not have particular naming conventions, then these conventions can be applied.
Folder Organization Conventions
The most recommended directory structure is following the MVC concept (MVC: The Most Vexing Conundrum).
In the root of your application keep only a dispatcher, typically called index.php, which will include the correct controllers.
Put your models in models folder, your controllers in controllers and your views in views.
You would probably have some global definitions and configuration files which can be placed in inc or config folder.
Various libraries (both procedural functions and OO classes) can stay in lib or library.
Some developers choose to put the administration in a folder called admin, but if you choose that route you would always need to watch out for the include paths.
So your directory structure may look like this:
Of course, when working with large applications you may see the need to add folders like external for third party libraries, ajax for scripts that will be called by ajax, data for saving temporary flat datafiles, etc.
Naming Conventions for Functions, Classes and Variables
- PHP function and class method names should be descriptive and written in small letters only. If more than one word is required to describe the function, then underscore should be used to connect the words. It is, in general, a good idea to have a descriptive name with two or more words. For example, a function calculating discount can be called calculate_discount() and a class method checking for unique usernames can be called unique_username().
- PHP variable names should be descriptive and written in small letters only. If more than one word is required to describe the function, then underscore should be used to connect the words. For example, a variable containing user’s age could be called $user_age
SQL Coding Guidelines
- All SQL Reserved words and functions should be written in ALL CAPS. For example these are SELECT, UPDATE, INSERT, DELETE, ALTER, FROM, INTO, VALUES, CURDATE(), CONCAT(), etc. This makes SQL statements much easier to read.
- All logical blocks in an SQL query should start in a new line. This means a typical SELECT query will have the following format:
SELECT field1, field2, field3… (put this on one or more lines)
FROM table1, table2… (next line or lines)
LEFT JOIN table1… (if join is needed - next line/s)
ON field1=field2… (if join is needed - starts on next line and goes across as many lines as needed)
GROUP BY field1, field2 (on next line, if GROUP BY is needed)
ORDER BY … LIMIT (both can go to the next line)
Putting an entire SQL query on one line is acceptable only when the query is very short and fits on one line without any word wrap.
- SQL queries can be placed in model or controller files. Placing SQL code in views/templates should be avoided at any cost.
We believe these simple yet important guidelines will help you write code much better. In keeping with our philosophy, we have not stated hard rules, but have given tips with enough flexibility to let you define your own style.