Do you use coding conventions? They help the code to speak for itself (with some help) and make the learning curve a little less steep. However do some conventions get in the way more than help?

A while back I was swapping comments back and forth with Tom McFarlin and Gary Jones on a post about coding conventions and the use of notation to describe what the intent behind a variable or function is. Tom, as he states in his post, tends to use Hungarian notation. If you’re not familiar with this notation, basically you decorate your variables with letters(or symbols) to indicate the scope or type of a variable.

But I am not sure decorating variables or functions work in a WordPress plugin.

My usual method on deciding what notation to use, usually depends on what domain or community I am working in. If I am working on a .NET application then I will use the conventions associated with working on .NET code. If I am working on a WordPress application then I will use the WordPress conventions.

But the way we code is not always covered by a convention so we are free to do what we want and in WordPress I do not think decoration would work.

PHP is not a strongly typed language, this has both upsides and down sides. So decorating a variable with the type the variable should hold initially makes sense. It should make the code easier to read. The downside of this is that it can make bug fixing tricky. But the upside

is you can make the intent behind the code clearer.

Let’s take an example. Say you wrote a find function for something that returned results as an array. If there were no results found then the array would be empty and you could do a count to see if there were any results or not.

$results = do_my_find( 'find fish' ); if( 0 !== count( $results ) ) { $this->feed_my_cat_fish( $results ); } 1 2 3 4 $results = do_my_find ( 'find fish' ) ; if ( 0 !== count ( $results ) ) { $this -> feed_my_cat_fish ( $results ) ; }

However because we are not constrained by what type we return we can return false if no data is found and an array if we have results. So the code would look like this.

$results = do_my_find( 'find fish' ); if( false !== $results ) { $this->feed_my_cat_fish( $results ); } 1 2 3 4 $results = do_my_find ( 'find fish' ) ; if ( false !== $results ) { $this -> feed_my_cat_fish ( $results ) ; }

Now this can be used as a very powerful tool because it makes the intent of the code clearer, in my opinion, and causes the reader of the code to use fewer CPU cycles in their brain. Always a good thing!

But if we want decorate that variable, $results, to indicate what type it should hold then what do we decorate it with? We do not want to decorate it in a way that suggests that the variable will always be an array because this could lead a reader to the wrong conclusion later in the code. We do not want to decorate the variable to indicate it is a boolean for the same reason.

Now some might say that returning a different type in a variable depending on the outcome of an operation in a function is bad practice. However I would argue that I want to use any tool in my toolbox to produce readable code. I am not going to say “I’m not going to use a hammer, because this particular tray in my toolbox should only contain wrenches”.

Like any powerful feature it should be used with caution.

So how do we make sure our code is understandable? Documentation. For my feed_my_cat_fish function above we would add comments at the top of the function to say that the function returns a boolean if no results are found. As Gary Jones said in the comments of this post use documentation to keep your functions and variables DRY.

Do you document your functions and variables? I would love to know so leave a comment.