4.2 Best Practices for Implementing Custom Code Snippets

Have a custom code snippet you want to implement on your site? Welcome to WordPress customizing!

Regardless of where you find the snippet you want to implement–or even if you come up with it yourself–the best practice for adding custom code is to create a functionality plugin, unless it’s something specific to your theme, in which case best practice is to make sure you’re using a child theme, then add the customization to your child theme’s functions.php file.

Check the copy and paste

We share code snippets (sometimes called “gists” if hosted at gist.github.com) throughout this site.

There are several gotchas to look out for when copying and pasting code.

Remove the Opening <?php Tag

PHP code snippets will most often start with an opening <?php tag. This is added only to enable syntax highlighting within a gist, which makes the embedded code much easier to read.

You should always remove the initial <?php tag (not all of them if there are more than one) when copying and pasting into your own code because your plugin or theme .php file already has one at or near the beginning of the file.

The exception to this is if the snippet is a complete file replacement, such as a file called single-event.php with instructions that it is a template override–a complete PHP file, not just a snippet. Template override files should go in your child theme, not in your main/parent theme and not in a plugin.

Watch out for garbled HTML

Many people use gist.github.com or similar sites like Pastebin, Cacher.io, or GitLab Snippets because they offer syntax highlighting, revision history, and most importantly do not garble the code by accidentally parsing the snippet’s code as HTML.

For example, if you see something like $this->method_name() turned into $this-&gt;method_name(), the “greater than” arrow got turned into the HTML entity version of it. Pasting the &gt; instead of the > will break your site. Another common issue to look out for: straight/plain quotes getting converted to curly quotes.

CSS and JavaScript Snippets

CSS and JavaScript snippets are less common than PHP snippets in our Help Desk, but we have quite a few of them.

You can add custom CSS code via your child theme’s style.css file, via WordPress 4.7’s Customizer CSS settings, or via a third-party plugin (not guaranteed or supported by us), such as:

• SiteOrigin CSS helps you visually build CSS selectors via its Inspector and Visual Editor, which is the most user-friendly for less-experienced site owners.
• Simple Custom CSS
• Jetpack supports regular CSS and the LESS and Sass pre-processors.

If you are unsure how CSS works, Jetpack’s Custom Design reference may prove helpful.

Interestingly, JavaScript snippets are almost always implemented as PHP snippets so WordPress’ enqueuing logic can be used. Doing so ensures JavaScript only loads when appropriate and only loads in the correct order so as to not create console errors at your site.

Best Practices

• Most code snippets should go in a functionality plugin.
  • This can be a single plugin with multiple snippets in it.
  • Or you could have a single plugin per snippet.
• You should never modify a theme’s code (a.k.a. the parent theme) unless you are the theme author (in case you are confused, you are not the theme author).
  • All theme customizations should be done in a child theme.
  • If a code snippet is theme-specific, it is acceptable to put it in your child theme’s functions.php file.
• At the very least, always read all of the code’s comments before pasting someone else’s snippet into your site.
  • Comments are grayed out when syntax highlighting is in effect.
  • Comments are like billboards and road signs. They might tell you to change the value of a variable in order to run correctly on your site. They can explain what the code is doing, in which context it executes, or what other bits of code are related to this bit of code.
• Try to read the actual code, not just the comments.
  • While you might not know what the code is doing, the function names normally give you a clue about what it does.
  • Reading a short code snippet and understanding what it does feels empowering and encouraging. It is also safer for your site because you will have a better idea of where to find a possible culprit when something goes haywire, such as if the snippet is not compatible with a version of The Events Calendar that is released 2 years from now.

Always do these things

• Before adding any custom code (even just pasting a code snippet that is supposed to do a simple thing), ensure you have a restorable backup of both your database and files.
• We strongly recommend performing any and all modifications first on a staging site before modifying anything on your live/production site.
• Share your feedback with the person who shared the code snippet with you. They took time to share something they expected would benefit you; take a minute to comment/reply back that it worked or how you fixed it to get it to work. And feel free to link others to it to expand the code’s positive influence!
• Share your own code snippets, too! If you have a snippet that others might benefit from, add helpful comments, remove any sensitive information, and create a new gist. You can paste the gist link in our Help Desk, on social media, or in an email to a friend.