coding-guidelines.md

Coding Standards & Guidelines

These are some things to keep in mind when writing code for Jetpack plugin. Please follow them to speed up the review process and get your code merged faster.

Versions supported

• Jetpack supports PHP 5.6, as per WordPress' own requirements. Keep that in mind when developing for Jetpack.
• Jetpack follows WordPress Core's standards, with a few additions. The best way to ensure that you adhere to those standards is to set up your IDE as per the recommendations here.
• Jetpack supports the WP current version and the immediate previous version. So if WP version is 4.6, Jetpack will support it, as well as 4.5. It's desirable that when Jetpack is installed in older versions, it doesn't fail in a severe way.
• We support the latest two versions of all major browsers, except IE, where we currently only support 11 and Edge. (see Browse Happy for current latest versions).

General

• Install PHP Code Sniffer Code Sniffer rules for Jetpack Coding Standards. They will make it easier for you to notice any missing documentation or coding standards you should respect. Most IDEs display warnings and notices inside the editor, making it easy to inspect your code.
• If coding a module, make sure you declare the module in the inline doc, like this. The same applies for filters or actions, as shown here.
• Sanitize URLs, attributes, everything. WordPress.com VIP has this nice article about the topic.
• Create unit tests if you can (here are the Jetpack plugin tests for reference). If you're not familiar with Unit Testing, you can check this tutorial.

Deprecating code

When deprecating code in Jetpack (removing / renaming files, classes, functions, methods), there are a few things to keep in mind:

1. Other plugins / themes may be relying on that code, so we cannot just remove it. A quick way to gauge the use of a function can be to search for it in OpenGrok and WPDirectory.
2. Deleting a file that was loaded and in use in the previous release can cause Fatal Errors on sites with aggressive OpCache setups.

For these reasons, here are a few guidelines you can follow:

• Instead of deleting files, mark them as deprecated first with _deprecated_file.
• Deprecate classes, functions, and methods in the same way, while still returning its replacement if there is one.
• Deprecated code should remain in Jetpack for 6 months, so third-parties have time to find out about the deprecations and update their codebase.
• If possible, reach out to partners who rely on deprecated code to let them know when the code will be removed, and how they can update.
• If necessary, you can publish an update guide on developer.jetpack.com to help people update.

Widgets

• Make them support Customizer's Selective Refresh. Here's an article about it.
• Some Widgets ported from WordPress.com must only be registered if Jetpack is connected.
• Add the jetpack_widget_name filter to the widget title as shown here.

Translations

• Where it applies, make strings available for translation.
• Instead of __, _e, _x and similar functions, use their safe versions esc_html__, esc_html_e, esc_html_x and others where possible.
• Add the jetpack text domain to the translation functions.

Where should my code live?

Here are some general guidelines when considering adding new functionality:

• Packages
• Modules (@todo)
• module-extras.php (@todo)