When wrestling with WordPress commenting standards in my own development adventures, I realized I needed a quick reference guide to streamline the process. So, I did what any self-respecting developer would do: I created one. And guess what? You’ve just found it! Welcome to my personal “WordPress Commenting Standards: The Easy-Peasy Guide“.

This guide is more than just a compilation of best practices. It’s a distilled version of my experiences and insights, following the trail marked by WordPress coding and PHP DocBlock standards.

By the end of this article, you’ll have a handy reference that not only makes your code cleaner and easier to understand but also makes future maintenance and debugging a breeze. So, buckle up, and let’s dive into the wonderful world of WordPress commenting standards together!

WordPress Commenting Standards: Practical Examples

Welcome to the hands-on part of our guide! We’re diving into some live action now, illustrating how to apply WordPress commenting standards to your code. We’ll cover everything from hooks to classes to functions and file headers, all the while keeping DocBlock standards in sharp focus.

Good commenting isn’t just about annotating your code – it’s about creating a roadmap for anyone who interacts with it in the future. So, are you ready to see these standards come alive? Let’s dive in!

In this section, we’re going to tackle a crucial aspect of plugin development: adding a proper comment header to your plugin file.

Before we embark, remember that adhering to best practices not only ensures your plugin’s quality but also improves its visibility in the plugin directory. We all want our creations to be discovered, right? So, let’s make sure your plugin stands out from the crowd and gets the attention it deserves.

/**
 * Plugin Name
 *
 * @package           PluginPackage
 * @author            Your Name
 * @copyright         2019 Your Name or Company Name
 * @license           GPL-2.0-or-later
 *
 * @wordpress-plugin
 * Plugin Name:       Plugin Name
 * Plugin URI:        https://example.com/plugin-name
 * Description:       Description of the plugin.
 * Version:           1.0.0
 * Requires at least: 5.2
 * Requires PHP:      7.2
 * Author:            Ben Marshall
 * Author URI:        https://benmarshall.me
 * Text Domain:       plugin-slug
 * License:           GPL v2 or later
 * License URI:       http://www.gnu.org/licenses/gpl-2.0.txt
 * Update URI:        https://example.com/my-plugin/
 */

Additional fields include:

/**
 * Network: true (should be left out when not needed)
 * Domain path: /languages
 */

/*
 * Theme Name: Ben Marshall
 * Theme URI: https://benmarshall.me
 * Author: Ben Marshall
 * Author URI: https://benmarshall.me
 * Description: Custom WordPress block theme for benmarshall.me.
 * Tags: (see https://make.wordpress.org/themes/handbook/review/required/theme-tags/)
 * Version: 1.0
 * Requires at least: 5.0
 * Tested up to: 5.4
 * Requires PHP: 7.0
 * License: GNU General Public License v2 or later
 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: benmarshall
*/

/*
 * Theme Name:   Twenty Fifteen Child
 * Theme URI:    http://example.com/twenty-fifteen-child/
 * Description:  Twenty Fifteen Child Theme
 * Author:       John Doe
 * Author URI:   http://example.com
 * Template:     twentyfifteen
 * Version:      1.0.0
 * License:      GNU General Public License v2 or later
 * License URI:  http://www.gnu.org/licenses/gpl-2.0.html
 * Tags:         light, dark, two-columns, right-sidebar, responsive-layout, accessibility-ready
 * Text Domain:  twentyfifteenchild
 */

/**
 * Filters the post content.
 *
 * This function applies to the content of the current post. For more details on its usage and hooks, see the WordPress Developer Reference.
 *
 * @see https://developer.wordpress.org/reference/hooks/the_content/
 *
 * @param string $content Content of the current post.
 *
 * @return string Updated content of the current post.
 */

add_filter(
    'the_content',
    function ( $content ) {
        return $content;
    }
);

Embrace WordPress commenting standards! Adding comments to your Gutenberg block’s PHP file header is vital for code clarity. Check out this example of a proper block header. Let’s make your blocks shine!

/**
 * Title: Footer with text, social links.
 * Slug: theme-slug/footer-default
 * Description: Description of the pattern
 * Categories: text, site-footer
 * Keywords: Comma separated keywords under which the pattern can be found
 * Block Types: core/template-part/footer
 * Post Types: Comma separated post types the pattern should be limited to. (defaults to all)
 * Inserter: Whether or not the pattern should be shown in the inserter (defaults to true)
 * Viewport Width: 1280
 *
 * @package MyAwesomeBlock
 */

Voilà! This magical snippet showcases the key elements you need to include in your block header, such as the block title, slug, description, categories, keywords, block types, and post types. It’s like a little introduction that makes your block shine among the coding galaxies.

Now, let’s take a fun little detour to explore the magical world of… translator comments! Sounds like something straight out of Harry Potter, doesn’t it? Well, it might not turn you into a master wizard, but it’ll definitely make you a WordPress pro.

First things first, what’s this whole “translator comment” thingy about? In simple terms, it’s a nifty little feature that helps those friendly translators out there understand what your code is all about. When you’re adding text that needs translation, you can leave a comment that says, “Hey, translator, this is what’s going on here.” It’s like leaving a note for your future self (or someone else), but in a geeky, coder-friendly kind of way.

Let’s get our hands dirty and play around with some code, shall we? Here’s an example of a translator comment in action:

/* translators: %s: Name of a city */
printf( __( 'I love %s.', 'text-domain' ), 'Paris' );

In this snippet, we’re using the translator comment to explain that ‘%s‘ will be replaced by the name of a city. It’s like we’re whispering a secret message to the translator: “Psst, this is a city name!” This way, the translator knows exactly what’s going on and can provide a much better translation. Isn’t that neat?

Here’s another example with multiple string replacements:

// Translators: 1: Name of a person, 2: Name of their pet
printf( __( 'Meet %1$s, they have a cute pet named %2$s.', 'text-domain' ), 'Alex', 'Buddy' );

In this little gem of a code snippet, ‘%1$s‘ gets replaced by a person’s name, while ‘%2$s‘ slides in the name of their adorable pet. Our translator comment makes it clear as day for any translator who comes across our code. They’ll know exactly what each placeholder stands for and translate accordingly.

It’s not just about being nice to the translators (although that’s a big part of it!), but it’s also about maintaining clean, readable code. Your future self will thank you for these little breadcrumbs you leave behind.

What’s more, these translator comments also play a crucial role in keeping your site’s content accessible to everyone around the globe. By making it easier for translators, you’re ensuring that your website truly speaks the language of its users, no matter where they’re from. Pretty cool, right?

So, next time you’re up to your eyeballs in code, remember to drop in a friendly little translator comment. It’s like a small act of kindness that goes a long way in the bustling universe of WordPress.

PHPCS is an awesome tool that ensures your code aligns with a specific set of standards and rules. It’s like having a trusty coding buddy who keeps you on the right path. Whether you’re part of a development team, working on your own, or even integrating with a CI/CD pipeline, PHPCS has got your back.

But hey, here’s the thing: We all know that sometimes, we come across code that’s not quite ready for the PHPCS scrutiny. It could be those snippets of legacy code that are waiting patiently for a refactor, or maybe you’re extending from third-party objects that don’t quite match the standard.

Luckily, there’s a way to handle this with… comments! Let me show you how to gracefully ignore code from PHPCS:

<?php
// phpcs:ignoreFile

// phpcs:ignore
public function store($myArray)

public function store($myArray) // phpcs:ignore

// phpcs:disable
public function store($myArray): void
{
    if (count($myArray) > 3) {
        // Humongous amount of legacy code you don't want to look at
    }

    return;
}
// phpcs:enable

With // phpcs:ignore and // phpcs:disable you can also specify which messages, sniffs, categories or standards you would like to disable, for example:

// phpcs:ignore Squiz.Arrays.ArrayDeclaration.SingleLineNotAllowed
$foo = [1,2,3];

If you want to read more about this subject, you can visit the wiki. Some of the examples were taken from there.

Remember, this technique should be used sparingly and only when absolutely necessary. We still want to maintain those high coding standards throughout our projects!