Introducing WPCodeBin, a better way to share WordPress Code Snippets

WPCodeBin is a free service for sharing WordPress Code Snippets on social media, without having to paste code in comments or posts.

One thing we need to be aware of is that we don't write code for machines to understand, we write code that humans should understand. We read code more than we write it, so writing clean code that's easy to maintain and understand is always a thing we should strive for.

Avoid comments (when possible)

As programmers, we were taught that it is always good to document your code. But when you think deeper, you realize comments are just a failure to express what you want in code.

For the sake of commenting, we often add redundant comments that add no extra value to the code. For example:

The comment here adds no value, and it's just extra noise around the code.

// Increment x
$x++;

Some other comments can be easily replaced with a descriptive variable name, for example:

// The number of categories to show
$n = 4;

A better way would be to write the above code like:

$number_of_categories_to_show = 4;

If you want to take it even further, you could replace complicated logic with a function with a descriptive name, for example:

// Check if business conditions are met
if(current_user_can('manage_options') && the_title() == 'Cool post') {
// Do something
}

This can be rewritten as:

if(conditions_are_met()){
// Do something
}

function conditions_are_met() {
return current_user_can('manage_options') && the_title() == 'Cool post';
}

One other disadvantage of comments is that they often can become outdated, and start to lie about what the commented code does. Programmers don't usually update comments as well as the code they write. So it's better to avoid them when possible.

A good example of when you should use comments would be when you do something that's clever or overly-optimized, for example, a regular expression, or an optimization that won't make sense for you in the future.

Use guard clauses to simplify conditionals

One of the main things that make code harder to read are conditionals, and even worse, nested conditionals. Nested conditionals can be avoided in a number of ways, but one of the easiest ways is to use guard clauses at the beginning of a function.

Guard clauses make sure that the conditions for that code to execute are met before the main body of the function gets executed. Instead of wrapping a whole method's code in an if statement that checks if a condition is met, test all the conditions before the code gets executed.

OOP and polymorphism provide better ways to get rid of conditionals even further, but that is a very advanced topic, but that is a very advanced topic and doesn't make sense in the context of WordPress Code Snippets.

Fail Fast

This ties into the above point. Check all your preconditions before running the main code of a function. If these preconditions are not met, make sure you return or throw an exception early.

This will make the preconditions that are needed to run code obvious when you first glance over a function.

Don't repeat yourself

Having multiple sources of truth for code can become confusing and create a lot of potential bugs and problems. Try to avoid using duplicate code in your code snippets. If the same functionality is required in more places, place that functionality in a function and call it wherever is needed.

This makes sure that there is only one source of truth for all your logic, and in case you need to make a change, you would need to change the code in only one place, leading to code that's easier to change and improve in the future.

Don't use magic numbers

Magic numbers are numbers in your code that have a meaning, but that meaning is hidden. Magic numbers make it hard for you to remember what a number in your code snippet might mean.

A best practice would be to replace magic numbers with constants or variables, that have a descriptive name and state the purpose of the number.

For example, if you want to show 4 categories on the homepage, you could use a query that limits the number of categories to 4. Instead of using the number 4 in code, extract a variable with the name $number_of_categories to show, or define a constant NUMBER_OF_CATEGORIES_TO_SHOW, this gives a name to the number 4 in that context.

Use descriptive variable names

There are 2 things that are hard in computer science, cache invalidation and naming things.

Using descriptive variable names makes the code easier to read and understand. It might be obvious to you at the time of writing a code snippet what a variable is, but as time goes by, you will forget what that variable was supposed to represent.

Using descriptive names also is a great way to reduce the number of comments in your code, allowing the code to document itself.

Be consistent

It's very important when writing code that we are consistent. WordPress provides a set of coding standards that we can follow. But even if you don't like the WordPress standard, that's not as important as being consistent. Use the same indentation across all your code, the same spacing, and curly brace placement.

This will make the code easier to understand and reason about