Coding standards

In WordPress plugin development we primarily follow WordPress Coding Standards, but for some parts we use our own coding standards and styles. Below is a list of our coding standards that are different from WordPress Coding Standards.

Add action/filter just before the function definition

Call add_action() or add_filter() first, and then define the callback function.

add_action( 'init', 'do_something', 10, 0 );

function do_something() {
  // ...
}

By performing the tasks in this order, you can easily grasp the correspondence between the hook and callback. This is useful, especially when the function definition takes hundreds of lines.

When add_action() or add_filter() is called, the system doesn’t check if the callback function passed as the second parameter really exists. It only needs to know the name of the function.

Always set four arguments to add_action() or add_filter()

Although the third and fourth arguments are optional to set, always set all four arguments when you call add_action() or add_filter(). It is especially important to explicitly set the fourth argument ($accepted_args).

add_action( 'init', 'do_something', 10, 0 ); // The fourth argument, $accepted_args, is zero.

The default value of $accepted_args is 1, and you need to increase this value when the callback function takes two parameters or more. However, this is something developers often forget to do. If you consciously set the argument, you’ll be able to avoid this mistake.

There is another reason to do it this way. When the function used as an action/filter callback is also used as an independent function, and the function definition has default arguments, the use of the function may cause confusion that, in turn, makes debugging difficult.

add_action( 'init', 'do_something' );

function do_something( $arg1 = 'some value' ) {
  // $arg1 is 'some value'? or null?
}

In the case of the preceding example, are you sure of what value is set in the $arg1 variable? do_something() sets $arg1 to ‘some value‘ when you omit to set the argument. On the other hand, the init action passes a null value through $arg1 by default. Is $arg1some value‘ or null?

Use and and or instead of && and ||

Use and and or operators, instead of && and ||, in a PHP conditional expression, as in the following:

if ( $a < 1 and 2 < $b or $c < 3 and 4 < $d ) {
  // ...
}

The conditional logic becomes clearer if you use and and or.

The and and or operators work the same way as && and ||, but they have lower precedence and so expressions, including assignment operators, like the following, work as intended:

$a = 10;

if ( $a = 5 and $a < 6 ) { // True
  // ...
}

Use blank lines aggressively

Use blank lines aggressively in your code when it improves readability.

Always insert a blank line before and after a control structure (if, while, foreach, etc.).

do_something();

if ( cond ) {
  do_another_thing();
}

$var = "value";

When you add a comment line before lines commented by it, insert a blank line before the comment line.

do_something();

// this comment line explains following lines
$var = "value";

Exceptional cases are the first and last lines in a function definition. You don’t need blank lines there.

function do_something() {
  // this comment line explains following lines
  $var = "value";

  if ( cond ) {
    do_another_thing();
  }
}

No indent in the middle of a line

We use indentation only at the beginning of a line. Using indentation in the middle of a line doesn’t improve readability and only becomes troublesome when you add a line next to it.

// Bad example. Don't code like this!
array(
  'bla'             => "Bla",
  'bla_bla'         => "Bla bla",
  'bla_bla_bla'     => "Bla bla bla",
  'bla_bla_bla_bla' => "Bla bla bla bla",
);

Use XHTML syntax

While HTML5 vocabularies are mainly used, we use the XHTML syntax whenever generating HTML output.

Thus, we don’t omit end tags or attribute values even where omission is permitted.

Re-index array items

Some array functions, such as array_filter(), preserve array keys. When the array was numerically indexed (in other words, a non-associative array), this is a feature that may cause confusion:

$input_array = array( "China", "India", "San Marino" );

$output_array = array_filter(
  $input_array,
  function ( $item ) {
    return 5 < strlen( $item );
  }
);

echo json_encode( $output_array ); // {"2":"San Marino"}
echo $output_array[0]; // Notice: Undefined offset: 0

$output_array = array_values( $output_array ); // Re-indexing

echo json_encode( $output_array ); // ["San Marino"]
echo $output_array[0]; // San Marino

To avoid this, re-indexing the result array items using array_values() is advised.

Just another contact form plugin for WordPress. Simple but flexible.