PHP Naming Conventions

TAIT's Organization

T8s.Org: Tait's; TAIT's; and Taits!

 
 
 
 

Archives

Categories

PHP Naming Conventions

Name conventions for PHP variable names, array names, array keys, property names, object names, function names, class names, constant names, folder names, and file names.

  • use word separators, not compound words.

  • use ‘_’ (underscore) as the word separator, except in folder names and file names.

  • use ‘-‘ (hyphen or dash) as the word separator in folder names and file names.

  • use ONLY lowercase letters and numbers, except Class_Names and CONSTANTS.

  • use uppercase (Capitals) as the first letter of words in Class_Names ONLY!

  • use ALL uppercase (CAPITALS) and numbers in CONSTANT_NAMES ONLY (ex. VERSION_NUMBER).

  • use natural words.

  • don’t use compound words, use word separators.

  • don’t use ‘-‘ (dash) as the word separator, except in folder names and file names.

  • don’t use ‘ ‘ (space) as the word separator.

  • don’t use ‘~’ (tilde) as the word separator.

  • don’t use \x7f-\xff

  • don’t use uppercase (Capitals), except in Class_Names and CONSTANT_NAMES.

  • don’t use uncommon abbreviations.

  • don’t use camelCase.

Examples

Example That Fails

$array = array("hello" => "hi", "what-up" => "yup");
extract($array);
echo $hello; // hi
echo $what-up; // FAIL

Good Example

  class Website_News {
    private $my_title;
    private $our_summary;
    private $some_content;

    function get_title() {
      $this->my_title = CONSTANT_TITLE;
      return $this->my_title;
    }
  }
  $our_news = new Website_News;

REASONS

The rest of this document is devoted to specific reasons for specific naming conventions.  Why are these conventions more readable, and therefore, less prone to error (in coding or modifying), and less debugging time.

Underscore

Use ‘_’ (underscore) as the word separator, except in folder names and file names use a “-” (dash).

The Underscore is the most natural for reading names.  We normally read with a space between words.  Spaces (and dashes) are not allowed in many conventions (see failed example above), therefore, the underscore is the most like a natural space.

The underscore allows words that would sometimes be forced together like $webssite and $lessstamps, to be more readable as $webs_site and $less_stamps.

The underscore prevents errors from new php coders to experts alike.

The underscore is not valid on all systems for folder and file names, so for these use a dash for readability / less errors.

Lowercase

Use lowercase letters and numbers.

By using only lowercase letters (a-z), and numbers(0-9), there is no question of capitalization of names like $last_name or last-name().  Likewise, otherwise acceptable characters like “ñ” will often be confused for n in other language groups (and may not be recognized in some server configurations).

Class Names

Use uppercase (Capitals) as the first letter of words in Class_Names ONLY!

Class_Names names are extremely infrequently uses within a document.  Therefore, by using some uppercase (Capitals) in Class_Names makes sense to show it’s uniqueness.

Constant Names

Use ALL uppercase (CAPITALS) and numbers in CONSTANT_NAMES ONLY (ex. VERSION_NUMBER).

This allows them to be easily distinguished from things like function names.

Natural Words

Use natural words!

Natural words like $customer_last_name are so much more readable (fewer mistakes) than some unfamiliar abbreviations like $cln, or $ln, or $nl, or $n3… It may be easy for the original coder, but what about the coder who looks at this code for the first time (to modify it) or even for the original coder trying to make a modification after 5 years!

Use Word Separators, Not Compound Words!

Consider the difference between Children’s Laughter and Children Slaughter.  As a compound word in your name space, they would both be $childrenslaughter.

$dollarsexchange may sound good when you code it.  However, if is much more understandable if you use $dollars_exchange or $dollar_sex_change.

After some manipulation, you may have something you call an IT Scrap that you wish to save for later.  But $itscrap my later be understood to mean $its_crap instead of $it_scrap.

Use Natural Words with word spacers in your name space and you will not have these problems later.

Compound Words

Don’t Use Compound Words in your Name Space.

As an example, domain names are often compound words, that are frequently misinterpreted if not careful.  Back in 19-forgotten, I recall receiving a message about a new search engine, google.com.  Automatically I considered the domain name, and wondered why my friend wanted me to Go Ogle anything?

See Also:

  • Natural Words

Abbreviations

Don’t use uncommon abbreviations.

If $pres is acceptable for $president, wouldn’t $p also be acceptable?  Would $pt (first and last letters of president) be ok?  Of course $pi ( Pres-Ident ) could work as well!

It is better to use a more understandable natural word, than an abbreviation that may be misunderstood at a later date or by a different person.  Abbreviations are usually used to save a few letters and, in modern computers, this is not very critical.

The variable $president is a pretty understandable variable!

Best Practice is to have understandable natural words.

See Also:

  • Natural Words

Dash, Space, Tilde

Don’t use ‘-‘ (dash) as the word separator.
Don’t use ‘ ‘ (space) as the word separator.
Don’t use ‘~’ (tilde) as the word separator.

Tildes are often confused with dash / hyphen characters.

See Also:

  • Underscore

Other ASCII Letters

Don’t use \x7f-\xff
Don’t use uppercase (Capitals), except in Class_Names and CONSTANTS_NAMES.

Upper Latin ASCII letters ( \x7f-\xff ) are often confused by people, like “n” for “ñ”, and some servers do not understand some of these also.

The same is true for uppercase (capitals) in some cases (some servers accept the “S” is the same as “s” and “z” the same as “Z”.  Although this is becoming more rare, by using all lowercase (except in Class Names and Constant Names) we totally eliminate all these potential errors.

See Also:

  • Lowercase
  • Class Names
  • Constant Names

 

camelCase

Don’t use camelCase.

CamelCase is a hotly debated topic.  However it is easy to understand why we do not recommend it if you simply look at the history.

Way back in “19-forgotten”, computer programmers were (mostly) guys who spoke a different language than most people.  Geeks, gurus, computerese, and other terms came from that era.  It was a time when computer memory was measured in Bytes, and sometime kibibyte (then called kilobytes).

My work mainframe computer had 16KiB of Magnetic Core Memory (“Core” for short!).  It was called Core because it was actually tiny magnetic ferrite “cores” (like little donuts) strung on a matrix of wires! (Now you know the beginning for the term core!)  Bytes were very, very, very valuable, to the tune of hundreds of dollars per byte and millions of dollars per installation!

My first personal computer (that I hand wired and soldered together), had a whopping 256 bytes of memory!  That is not kibibyte (kilobytes?) or mebibyte (megabytes?), only simple bytes.  I added one kibibyte (then called one kilobyte) and it cost me well over US$1,000.00.  That was roughly one dollar per byte!

Today memory is cheap.  I regularly put in 4 GiB (four gibibyte or gigabytes) in new computers.

Back in the 19-forgottens we used initialisms, acronyms, bacronyms and mnemonics to shorten everything.  Saving even one byte. was very important!

CamelCase saved a byte back then!

Remember, these were geeks and gurus and people heavily into computer programing.  CamelCase became a part of computerese or computerSpeak.

Today’s PHP is much more human readable than Pascal, Aglol, PL!, Cobol, or Fortran ever was in the 19-forgottens.

Read These carefully…

 

1) ProgrammersHaveTrainedThemselvesToReadCamelCaseButItIsDifficultForTheRestOfUs

2) Programmers have trained themselves to read camel case, but it is difficult for the rest of us.

3) programmers_have_trained_themselves_to_read_camel_case_but_it_is_difficult_for_the_rest_of_us

 

If you thought that line #3 was easy to read, and line #2 was the easiest to read, but that line #1 was the hardest to read, CONGRATULATIONS, you are a normal human.

If you thought all three lines read about the same, you are likely a computerGeekGuru who has studies the ways of the past geeks, and you like camelCase!

Basically, a coding standard should make things better and easier, and therefore have fewer errors.  CamelCase tends to make things harder and more difficult to understand.

Remember the $lessstamps and $webssite examples in the beginning?  They really are not made much better with camelCase.  It is much easier, and much less error prone to used underscores to separate the words, as the below table shows (remember you never have to remember what you should make uppercase, because nothing is!)…

$lessstamps $webssite
$less_stamps $webs_site
$lessStamps $websSite

Don’t use camelCase!

See Also:

  • Understore
  • Lowercase
  • Class Names
  • Constant Names