International School of Engineering Web Software development Development Decoded
Home Products Allmostapp Testimonials About Us
one pix   one pix   | |
PHP  
Bookmark and Share
Add to Technorati Favorites

Naming conventions and guidelines

This entry is part 3 of 3 in the series Recipe for Great PHP Programming

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:

inc/
lib/
models/
controllers/
views/
index.php

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().
  • Javascript function and class names should be descriptive and should start with a small letter. If more than one word is required to name the function, then each new word (excluding the first word) should start with a capital letter with no other delimiters between the words. The idea behind this difference is to distinguish easily PHP from Javascript function and methods, and to comply with the most common standard of writing Javacsript code. For example, a Javascript function validating a form could be called validateForm() and not validate_form()
  • 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
  • Javascript variable names should be descriptive and should start with a small letter. If more than one word is required to name the function, then each new word (excluding the first word) should start with a capital letter with no other delimiters between the words. For example, a variable containing the user’s age could be called var userAge

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.



Discussion

Comments for “Naming conventions and guidelines”

 
OUR PRODUCTS
Celeroo Req 'n Spec
Smartest Way To Manage Requirements And Changes For Any Software Project   more
 
Free Trial Req 'n Spec
Celeroo Builder
Cheapest And Fastest Way To Build PHP Applications   more
 
Free Trial Builder
Celeroo Frame
Lean, Flexible And Transparent MVC PHP Framework       more
 
Download Frame

Subscribe to "Allmostapp: Empowering BAs to Build Apps from Ideas - Swiftly"

We will NOT share your info with any third party. PERIOD.
 
right-bg-img right-bg-img
  Who We Are | Contact Us  
  All Rights Reserved. Copyright © 2008 - 2017 International School of Engineering. Celeroo’s Blog and Training Center . Entries (RSS) Search Unleashed wordpress-email-newsletter-plugin-for-double-opt-in-subscription G Lock Powered by WordPress Theme by The Masterplan