Advertisement
Cheat Sheets

The WordPress Coding Standards: Naming Conventions and Function Arguments

by

In this series, we're taking a deep dive into the WordPress Coding Standards - specifically, the PHP coding standards - in order to evangelize and understand how quality WordPress code should be written.

Despite the fact that this is documented within the WordPress Developer Handbook, I think there's something to be said for understanding the rationale behind why some things are the way that they are.

Remember: Our ultimate goal is to make sure that we're writing code that conforms to the coding standards so that we, along with other developers, are able to more easily read, understand, and maintain code for themes, plugins, and applications built on top of WordPress.

In this post, we're going to be taking a look at how to handle naming conventions and function arguments.


Naming Conventions

Before spending any time elaborating on the points outlined in the coding standards, it's important to understand the role that naming conventions play in writing code regardless of what platform with which you're working.

Ultimately, naming conventions - regardless of if they are for classes, functions, variables, attributes, or arguments - should help to explicate the purpose that they serve.

By that, I mean that class names should typically be nouns, functions should typically be verbs, and variables, attributes, and arguments should explain the purpose that they serve within the context of the class or function in which they are to be defined. It's all about making the code as readable as possible.

Just as the Coding Standards state:

Don't abbreviate variable names un-necessarily; let the code be unambiguous and self-documenting.

This is a good rule of thumb regardless of what part of the code it is on which you're working.

Class Names

When it comes to working with WordPress, you're not likely to encounter classes unless you're doing one of two things:

  • Writing a custom library to work alongside a theme or application
  • Writing an OOP-based plugin

If you're simply working on the theme, you're more likely to be working with a set of functions - we'll be talking about those momentarily.

But for those who are working with plugins or their own libraries, it's important to remember that classes should typically be nouns - they should represent the purpose that they encapsulate and they should ideally do one thing and do it well.

For example, if you have a class called Local_File_Operations then it may be responsible for reading and writing files. It shouldn't be responsible for reading and writing files as well as, say, retrieving remote files.

According to the WordPress Coding Standards, classes should follow the following conventions:

  • Class names should use capitalized words separated by underscores.
  • Any acronyms should be all upper case.

Simple, right?

Practically speaking, this would look like the following:

  • class Local_File_Operations {}
  • class Remote_File_Operations {}
  • class HTTP_Request {}
  • class SQL_Manager {}

To reiterate: classes should also be nouns and should describe the single purpose they serve.

Function Names

As mentioned earlier, if classes are nouns that ideally represent a single idea or single purpose, then their methods should be the actions that they are able to take. As such, they should be verbs - they should indicate what action will be taken whenever they are called.

Furthermore, the arguments that they accept should also factor into the name of the function. For example, if a function is responsible for opening a file, then its parameter should be a file name. Since our goal should make it as easy as possible to read code, then it should read something like "have the local file manager read the file having the following file name."

In code, this may look something like this:

// The class definition
class Local_File_Manager {

	public function open_file( $filename ) {
		// Function implementation
	}

}

// How we'd use this code
$file_manager = new Local_File_Manager();
$file_manager->open_file( 'foo.txt' );

Of course, this still doesn't cover how functions should be written within the context of WordPress development. The Coding Standards state:

Use lowercase letters in variable, action, and function names (never camelCase). Separate words via underscores. Don't abbreviate variable names un-necessarily; let the code be unambiguous and self-documenting.

The first part of of the convention is easy enough to understand; however, I think developers have a propensity to take shortcuts when they are able. "Ah," we think, "$str makes sense here, and $number make sense here."

Of course, there are always worse - some developers resort to using single characters for their variable names (which is generally only acceptable within loops.)

Just as the Coding Standards state: Don't abbreviate variable names un-necessarily. Let the code be unambiguous and self-documenting.

Now, the truth is, code can only be unambiguous to a point. After all, that's why it's called code, right? This is why I think code comments should be used liberally.

Anyway, the bottom line is to lower case your method names, avoid all camel casing, separate by spacing, and be as specific as possible when naming your variables.

Variable Names

Variable names actually aren't much different from function names other than they represent a single value or a reference to a particular object. The naming conventions still follow what you'd expect:

  • Lower case (versus camelCase)
  • Separate spaces with underscores

One other convention that some developers use is what's known as Hungarian Notation which is where the type of value the variable stores is prefixed in front of the variable.

For example:

  • Strings will often be represented as $str_firstname
  • Numbers will be written as $i_tax or $num_tax
  • Arrays may be written as $arr_range
  • ...and so on

Honestly, the coding standards say nothing about this. On one hand, I do think that this makes for cleaner code in the overall scope of code, but there are a lot of developers who dislike Hungarian Notation.

Since the coding conventions say nothing about them, I'm hesitant to recommend them as I want to stay as close to standards as possible. As such, I have to recommend that it's best to follow the coding standards.

File Names

In keeping consistent with the theme of making our code as readable and self-documenting as possible, it makes sense that we pull this through our source code all the way to the files that we're going to make up our theme, plugin, or application.

According to the Coding Standards:

Files should be named descriptively using lowercase letters. Hyphens should separate words.

In keeping consistent with our previous example, let's say that we're working with Local_File_Operations then the file would be named class-local-file-operations.php.

Easy enough.

Next, if you're working on a plugin called Instagram_Foo then the file should be named instagram-foo.php; however, it is worth noting that if you use some type of advanced methods for developing your plugins such as keeping the plugin class file in its own file and then loading it using it another file, then your file structure may be:

  • class-instagram-foo.php
  • instagram-foo.php

Where instagram-foo.php is responsible for loading the class-instagram-foo.php. Of course, this only makes sense if you're using OOP when writing your WordPress plugins.


Function Arguments

When it comes to passing function arguments, it's important to remember that if function names describe the actions that are being taken by the class, then the argument should represent on what the function is actually operating.

From the Coding Standards:

Prefer string values to just true and false when calling functions.

Since boolean values can be unclear when passing values into a function, it makes it difficult to ascertain exactly what the function is doing.

For example, let's use the above example in a slightly different manner:

// The class definition
class Local_File_Manager {

	public function manage_file( $filename, true ) {

		if ( true ) {
			// Open the file
		} else {
			// Delete the file
		}

	}

}

// How we'd use this code
$file_manager = new Local_File_Manager();
$file_manager->manage_file( 'foo.txt', true );

Is more difficult to understand than, say, something like this:

// The class definition
class Local_File_Manager {

	public function open_file( $filename ) {
		// open the file
	}

	public function delete_file( $filename ) {
		// delete the file
	}

}

// How we'd use this code
$file_manager = new Local_File_Manager();
$file_manager->open_file( 'foo.txt' );
$file_manager->delete_file( 'foo.txt' );

On top of that, remember that arguments being passed into functions are still variables in and of themselves so they are subject to the variable naming conventions that we've detailed above.


Conclusion

We've taken an extended look at Naming Conventions and Function arguments in the Coding Standards. Hopefully this has helped to provide not only a guide for how to improve certain aspects of your WordPress code, but also to explain the rationale behind some of the practices.

In the next article, we're going to take a look at the significance of single quotes and double quotes within the context of working with strings in WordPress development.

There is a difference into how they are interpreted by PHP and there are conditions in which you should use one over the other and we'll be reviewing that in the next article.

Related Posts
  • Code
    PHP
    Object-Oriented Programming in WordPress: Functions and AttributesWordpress oop
    As we continue our discussion of object-oriented programming within the context of WordPress, it's time for us to begin talking about actual features of object-oriented programming. Though we've already covered classes, we needed to explore some foundational programming constructs before coming back around to some of the core object-oriented concepts. In this article, we're going to begin talking about functions and attributes: two foundational aspects of object-oriented programming.Read More…
  • Code
    Articles
    Introduction to WordPress App ThemesApp theme 400
    With the increasing growth rate of WordPress powered websites, the need for WordPress themes is rising. Multi-purpose themes are becoming highly popular among website owners. Many existing themes are built mainly to address blog functionality. But with the growth of WordPress web application development, we are in need of specialized themes for different purposes. These themes are known as app themes. In this article, we going to familiarize with the concept of app themes and their usage in real world.Read More…
  • Code
    Plugins
    Distributing Your Plugins in GitHub with Automatic UpdatesSensorsthumbnail
    This article will teach you that, with a little creative coding, you can host your own WordPress plugins in GitHub while still retaining the automatic update feature.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme From Static HTML: Releasing Your ThemeCreating wordpress theme from html 400
    If you've been following this series you now have a working WordPress theme. Your theme has a number of template files, including a page template and an archive template, and also has featured image support.Read More…
  • Code
    Theme Development
    Making the Perfect WordPress Theme: How to Code WellWp white 400
    In the previous part of this series; we went through various WordPress APIs that we should learn about, talked about the importance of making a theme translatable (or even better, releasing them already translated into other languages) and understood the concept of licensing themes and using licensed products with the themes. In this article, we're going to focus on code: We'll see how to code with WordPress coding standards, how to properly comment our code and how to validate and test the theme.Read More…
  • Code
    Cheat Sheets
    The WordPress Coding Standards: Bringing It All TogetherThe wordpress coding standards
    When it comes to writing a series of blog posts, one of the most challenging aspects as a reader is actually keeping up with every post that is published. Even if you do manage to try and keep up, posts that are in excess of 1,000 words - especially those that include code - can take time that many of us don't have especially when it comes to juggling our work lives, home lives, hobbies, and other things. So in order to make sure that the information presented throughout this series is still presented in a digestible way, I thought I'd experiment with doing a summary of the entire series. That way, for those of you who have missed an article or haven't had the time to sit down and go through each article, can still get the gist of each point mentioned throughout the articles. With that said, let's take a look at everything we covered when reviewing the WordPress Coding Standards.Read More…