First, some theory

In a fantasy world where unicorns poop chocolate fudge and everything is awesome, it all goes down somewhat like this: You talk with the client or end user, and you gather up a list of things they want. You collect and number these in a requirements document, braking them up into Functional requirements, Non-functional requirements, and other Design constraints. Then, you design a solution, write your tests, and implement your code. Once all of the requirements in the document are met, you are done, and you get paid. Easy! Deviate from this simple methodology at your own peril. (Oh, and you also then need to maintain, fix and improve the code you’ve written.)

As a software engineer, you should know that in addition to what the client asks for, there are always implicit requirements. For example, your code must be readable and maintainable, and it must be reliable (read: not too buggy). All of these are aspects of code quality. A client or end user will never ask you for these, but you should have them in your list of non-functional requirements.

Professional developers write simple, clear code where a novice would write complex, intricate code to solve that same problem. Sure, a lot of this is just a matter of practice and experience.

Dev tools can help you with code quality whether you’re novice or pro. They help you discover issues that you don’t know about, and they help you discover issues that you do know about, faster!

If you are developing themes or plugins, here’s two tools that you definitely want to use as a professional WordPress developer:

Improve WordPress PHP code smell with CodeSniffer

There are some styling guidelines that all WordPress developers should follow. Especially if you are aspiring to upload your code to wordpress.org, or to the Envato Market (ThemeForest or CodeCanyon), then you definitely want to follow these guidelines. Generally, these get encoded into your muscle memory pretty quickly, but it’s always a great idea to have a tool like PHP CodeSniffer that double-checks your code style.

On my Ubuntu machine, I was able to install PHP CodeSniffer easily with:

sudo apt install php-codesniffer

Then, it’s just a matter of loading the WordPress-specific set of rules. Go to your home directory and clone the project:

git clone https://github.com/WordPress/WordPress-Coding-Standards ~/wpcs

And tell CodeSniffer the location of these rules:

sudo phpcs --config-set installed_paths ~/wpcs

Check that the new rules are added into CodeSniffer with:

phpcs -i

Congratulations! You can now check your plugin for code style with a command such as:

phpcs --standard=Wordpress-Core /path/to/source/code/root/dir

If, like me, you’re using grunt for your build process, then there’s a nifty Grung plugin, grunt-phpcs. Just make sure to specify WordPress-core as the rule set. Here’s a grunt target that you might use:

phpcs: {
    plugin: {
        src: ['src/**/*.php']
    },
    options: {
        bin: '/usr/bin/phpcs',
        standard: 'WordPress-core'
    }
}

Run it against your code and you will get a number of improvement suggestions. Some of these can be applied automatically with PHPCBF (the PHP Code Beautifier and Fixer), or you can go through the list manually and apply each suggestion as you see fit. Many of the suggestions will be related to code indentation, but you will also see a large number of other suggestions that are more critical.

Improve WordPress PHP code correctness with phan

PHP is a very lenient language. It will let you get away with murder. This is something that novice programmers often enjoy. For professionals it’s a nightmare, as it makes spotting errors harder. PHP has thus gained somewhat of a notoriety for being a bad language, and is the butt of some clever jokes.

This isn’t something to worry about. It has happened to many respectable languages, including JavaScript. So nowadays we have use strict, which lets us only use The Good Parts of the language. You can do something similar with PHP.

My point is that static code analysis is not the hero you want, but it’s definitely the hero you deserve. Enter phan:

First, install it. It’s straightforward to install phan with composer:

composer require phan/phan

Now phan lives in your project’s vendor/ dir.

Next, create a configuration under your project dir, in .phan/config.php. This will tell phan what settings you want to run it with. Start with the example given here, and set your source code directories.

You will also want to point to some third-party code, including the directory of your WordPress installation, since your code will invariably use WordPress functions and types.

You can also use this config file to exclude some rules, so that phan does not check for them. Here’s the complete list of phan plugins.

When all is set, you can call phan on your code with:

vendor/bin/phan

I don’t care how pro you are, you will definitely get a list of suggestions on how to improve your code.

Conclusion

Using phpcs and phan together, you will avoid a large number of errors that would otherwise likely go undetected. These include errors with translator comments over strings, phpDoc formatting errors, variable type errors, errors related to sentinel values such as null, and array indexing errors.

Always use these two tools together with phpunit when you write code. You will write more readable, maintainable, correct and robust code that you can feel confident about.

The post 💩 Your WordPress PHP code stinks! Here’s why. appeared first on Alexandros Georgiou.

Ten Things Every WordPress Plugin Developer Should Know

Actually you’ll probably want to read this before even starting your project; but better late than never! It’s packed with essential info that you should know. If you’ve missed any of the info in this article, go back to your code and fix it. There’s stuff about common practices, coding standards, etc.

PHP Coding Standards

This is a list of PHP coding standards that WordPress developers follow, both in core and in themes and plugins. It’s a requirement for submission to wordpress.org but it would be really nice to follow as many of these as possible even if you’re not planning to submit your code there.

Ideally you’ll want to use some tools for this. A quick search on GitHub reveals a number of syntax checkers. Here’s one that I use with Eclipse: https://github.com/edpittol/wordpress-eclipse-formatter, and another one for CodeSniffer (which can integrate nicely with a number of IDEs): https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.

Whatever you use, it doesn’t hurt to double check your code one last time. In Eclipse Formatter for instance, there is no way to check for “Yoda” conditions as far as I know, so you’ll want to manually check for those if you’re using it.

JavaScript Coding Standards

Have you checked your PHP code for compliance to the coding standards? Good! Get ready to do it again, this time for your JavaScript files; at least the unminified copies of them. Here’s a project that uses ESLint to help you enforce the standards: https://www.npmjs.com/package/eslint-plugin-wordpress. If you have a lot of JavaScript in your code, it might pay to integrate this into your pre-build checks, but as with PHP, always have one last look using your eyeballs.

WordPress plugins

If you’re writing a plugin, this is a short list of conditions that your project must meet before you publish to WordPress.org. It has more to do with functionality than standards, and essentially it’s about not being evil with your code.

Detailed Plugin Guidelines

This is essentially a longer version of the above. A definite must read if you’re publishing to WordPress.org. It’s about licensing, versioning, what you can and can’t do, etc.

Theme Review Process

If you’re writing a theme that you plan to publish to WordPress.org, check that it at least conforms to all the required items and try to conform to as many recommended items as possible. The write-up for the recommended guidelines is not complete as of the writing of this article, but there’s some very useful guidelines in there.

Theme Unit Test

Again, if you’re writing a theme for WordPress.org, you will also want to check a number of things against the provided Theme Unit Test. It’s probably a good idea to do this even if you’re publishing elsewhere.

ThemeForest General File Preparation Guidelines

If you’re publishing to ThemeForest, you will have to follow these guidelines on how to bundle your files.

WordPress Phase 1 Submission Requirements – Q&A

This is a list of guidelines to follow before submitting to ThemeForest. There’s a number of things listed that are not allowed, so make sure to check.

A step-by-step guide to the upload process

When uploading to ThemeForest, you will also want to follow these guidelines. They are mostly about the upload process but also include some information about how to bundle your files.

Professional WordPress: Design and Development

Finally, this is a book, not an actual checklist, but still I recommend that you at least glance through the table of contents. I’ve found this book very helpful. It covers all topics related to WordPress development and it’s very likely that whatever it is you’re trying to do, there might be a better way of doing it. WordPress is a complex system and it’s only getting more complex by the day.

My recommendation is that you go through the table of contents and read any chapter that talks about things you do in your theme or plugin. There are things you might have missed.

Too meta? Perhaps! But no matter what and where you’re publishing, if you want to be professional about it, don’t assume you know everything. At least glance through all of these guidelines.

The post ☑ WordPress checklists to go through before publishing a theme or plugin appeared first on Alexandros Georgiou.