The WordPress Coding Standards: Naming Conventions and Function Arguments

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' );

				
					
				1
2
3
4
5
6
7
8
9
10
11
12

						// 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 );

				
					
				1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

						// 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' );

				
					
				1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

						// 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.

Fonte: http://code.tutsplus.com/articles/the-wordpress-coding-standards-naming-conventions-and-function-arguments–wp-31683

Facebook Comments

Rate this post

Post Views: 36

Wordpress