The following details the coding conventions and markup styles used throughout the project in order to maintain a consistent structural style. The purpose of maintaining these set of standards is to create consistent, clean codebase that is easy to read making it easier to maintain and collaborate.

While the Shopp project does mostly follow WordPress Coding Standards, there are exceptions and as such we restate the entirety of our standards here to prevent jumping back and forth.

PHP


PHP Tags

Always use complete PHP tags as it is safer and best practice. NEVER use shorthand tags for PHP code. Many servers have shorthand tags disabled for PHP.

Correct

<?php statement(); ?>

Incorrect

<? statement: ?>
<?=$var?>

Important: You should omit the closing PHP tag at the end of a file. If you do not, make sure you remove trailing whitespace.

Closing PHP Tag

A closing tag (?>) should not be used to terminate a file containing only class or function definitions (though the file may contain closing tags) to reduce the risk of whitespace leaking into the page output.

Quotes

Quotes should be used following a practice that avoids escaping when possible.

Single Quotes are used for literal strings or string that are not evaluated.

echo '<a href="http://website.com">Link</a>';

Double Quotes are used for evaluated strings, strings that include variables that are evaluated at runtime.

$query = "SELECT $columns FROM $table where $where";

Strings that go into HTML attributes should run through the WordPress esc_attr() so that quotes do not end the attribute value and invalidate the HTML and cause security problems.

Spacing

Remove Trailing Spaces

Remove trailing spaces at the end of each line of code and blank lines at the end of files.

Most IDEs and programming-aware text editors have a feature or plugin or extension to automatically remove trailling whitespace from files on save. If yours does not, it is strongly recommended that you switch to a new editor that can be setup to perform this automatically.

Space Usage

Always put spaces after commas and on both side of logical, comparison, string and assignment operators.

x == 23
foo && bar
! foo
array( 1, 2, 3 )
$baz . '-5'
$term .= 'X'

Put spaces on both sides of opening and closing parenthesis of if, elseif, foreach, for, switch, and while blocks.

foreach ( $foo as $bar ) { ...

When defining a function a space should be used between the name and the parenthesis along with normal parenthesis conventions inside the argument interface:

function function_name ( $param1 = 'foo', $param2 = 'bar' ) { ...

When calling a function, the parenthesis should directly follow the name with no space:

function_name( $param1, func_param( $param2 ) );

When performing logical comparisons, space each element:

if ( ! $foo ) { ...

When referring to associative array elements, only include a space around the index if it is dynamically evaluated:

$x = $foo['bar']; // correct
$x = $foo[ 'bar' ]; // incorrect
$x = $foo[ $bar ]; // correct
$x = $foo[$bar]; // incorrect

Indentation

  • Indentation should always use real tabs and not spaces for initial indentation of lines.
  • Indentation should always be used inside of multi-line brace blocks and multi-line parenthesis blocks
  • Indenation inside of a line of code should use spaces instead of real tabs.

In the example below, a · represents a space and a ⇥ represents a tab.

$array = array(
    ⇥    'foo'····=>·'bar',
    ⇥    'boo'····=>·'far',
    ⇥    'sosumi'·=>·'beep'
);

Braces

Braces should be used for multiline blocks using Kernel Normal Form style braces.

if ( condition ) {
    action1();
    action2();
} elseif ( condition2 && condition3 ) {
    action3();
    action4();
} else {
    defaultaction();
}

Single line blocks should omit braces to simplify the code.

if ( condition )
    echo 'The fox jumped over the lazy dog...';
elseif ( condition2 )
    echo 'The dog jumped over the lazy fox...';
else
    echo 'The dog and the fox are both lazy';

For simple single-line actions, the condition should be combined on the same line as the action.

if ( condition1 ) action1();
elseif ( condition2 ) action2();
else defaultaction();

Naming Conventions

Use the simplest term possible, but not simpler.

Well thought out names provide a common cultural dictionary of consistent project terms that make communicating concepts to others much easier to understand. Meaning of a term becomes automatic to those well entrenched in the project, and easy to assign the meaning for those just starting to become involved in the project.

Functions & Methods

Always use lowercase letters for function names (never CamelCase or camelBack notation). Use the simplest, shortest word or compound word for function and method names whenever possible. In situations where a single short word name does not adequately describe the role of the function or conflicts with the name of a function in the same file or package of code or adds new ambiguity to an existing function in the code base, use two words separated by an underscore. Avoid three word function names unless absolutely necessary.

function action( $argument ) { ...

Classes & Interfaces

Use CamelCase for class names and interfaces as way of indicating formalizing the code organization. Avoid the use of underscores whenever possible. Class names that are not specific enough or represent core classes with the project code base should be prefixed with Shopp to prevent namespace conflicts.

class ShoppGatewayFramework extends ShoppModule { ...

Files & Directories

Directory names should always be lowercase single-word names or easily recognizable abbreviations such as: core, ui, js or css

Files whose primary purpose is to contain a formal class definition for an object should use CamelCase. File names should be lowercase single-word names for files containing a collection of functions (even in a static class which is used more for namespacing rather than formal organization) or a markup interface that mixes HTML and PHP.

File names that need to include multiple words that are all lower case should use hyphens to separate the words.

file-name.php

Query Statements

Use upper-case for all SQL keywords such as UPDATE and INSERT.

If the query is complex enough, use multiple lines with indentation.

Ternary Operator

Ternary operators should always use true statements, not false to prevent confusion, except in the case of ! empty() where testing for false in this case is more intuitive.

$download = ( 'download' == $record->type ) ? $record->id : false;
$classes = ( ! empty($classnames) ) join( ' ' , $classnames ) : '';

Yoda Conditions

if ( true == $do ) {
    $try = null;
} else {
    $donot = true;
}

When doing logical comparisons, always put the variable on the right side, constants or literals on the left.

This approach will produce a parse error when accidently leaving off an equal sign, leaving a single equal sign (assignment operator instead of logical operator). Using a constant first with an assignment operator will cause a parse error since you cannot assign a value to a constant like boolean true. If set the other way ( $do = true ) the assignment would be set to the variable, allowing the statement to evaluate to true and potentitally (read: most likely) causing a bug that you'll be hunting a good long while.

Weird it is. Get used to it, you will.

Readability Over Cleverness

In most cases, brevity in code results in better readability. There are times when this isn't true though.

isset( $var ) || $var = some_function();

Although the above line is clever, it takes a while to understand if you're not familiar with it. So, just write it like this:

if ( ! isset( $var ) ) $var = some_function();

else if or elseif

Most of Shopp uses elseif, but It doesn't matter.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile ยป

Plugin e-commerce for WordPress

Shared Ticket Bins

1.3 Development23% complete

 

Completed 23 of 102 tickets