Using Code Snippets from the Site

When copying code snippets from the site, it is important to copy clean code. This article discusses where to put it, how to copy it, how to read comments and where to make modifications. There are also some best practices to follow.

Where does this go?

Unless otherwise noted, custom code snippets will go into your theme’s functions.php, a custom plugin file, or wherever you store your custom code. Another popular option is to use a code snippets plugin, such as the aptly named Code Snippets.

Any one of the above options is fine, but I would suggest that you pick a method that works best for you and stick with that. Keep things consistently organized and it will be easier on you if any maintenance is needed in the future.

Personally, I use a combination of functions.php in my theme and a custom plugin file. Anything that is layout/style related goes in functions.php (since that’s part of the theme). Anything that is not related to look-and-feel goes into a custom plugin file.

Unless the article is discussing a bug patch (which is almost never), you will never ever modify a core plugin file.

Get It All

Make sure that you get all of the example code when you copy/paste.

Exception to “get it all”: You may see some code snippets that start with a PHP opening tag (<?php). In cases you find on this site, you must not include this. If the code is a code snippet hosted on GitHub, it will open with <?php so that the code is formatted when displayed on the site – but you should not include the tag. Copy/paste after the tag.

Code Comments

Comments are included in the code to help you. But they are not necessary to code execution. They are used to tell you a few different things:

They tell you what a specific line or section is doing.
They tell you what you can (or cannot/should not) change.
Other miscellaneous notes.

You don’t have to keep them in there, or you can – like I said, they are not necessary to code execution. But if you don’t know or aren’t sure what you can or cannot take out, leave them in. It doesn’t hurt.

What is most important is to know what is and what is not a comment. PHP comments are marked in two ways:

Double forward slashes

// Anything preceded by double forward slashes is a comment.
// This type of comment only marks a single line at a time (and
// anything that comes after it on that same line.  Anything on
// a line that comes after // is a comment and is ignored during
// code execution.

Multi-line comments

/*
Multi-line comments are preceded by &amp;quot;/*&amp;quot; and end with the reverse
of that
*/

/**
* Sometimes you&#039;ll see a multi-line comment used like this, with
* extra &amp;quot;*&amp;quot; leading each line.  Often, this is used in &amp;quot;docblock&amp;quot;
* comments, which are generally used as inline code documentation.
* Because docblocks are a specific standard, you&#039;ll see them
* used in WordPress itself as well as plugins and themes.
*
* The extra &amp;quot;*&amp;quot; leading the line doesn&#039;t mean anything in terms
* of defining the comment - the multi line comment is still only
* the leading and closing markers.
*/

Also keep in mind that anything within a code comment is not executed – so even if it is PHP, the comment indication means the code will be ignored as part of the comment. On occassion, you may see code “commented out” – so the code is there, but is ignored as a comment. Sometimes this may be used in debugging to turn on/off a section of code. The important thing to note is that if the code is marked as a comment, it is not executed.

Making Changes

While I try to make things as close to cut-paste-and-go as I possibly can, most of the time there will be something you need to change to make the snippet work for you.

Make sure that you have read the instructions as I will tell you what you need to do. Also, take note of the comments in the code. If you need to make a change to something (like specifying a field name), that will be noted in the comments.

I try to make things easy, so if possible, I’ll use a variable that you only need to change once and then use the variable throughout. Usually this will be commented to change the variable, and sometimes I’ll note in the comments that you generally don’t need to worry about changes after a certain point.

In situations where there are multiple functions in a single snippet and they all need a specific set of information, I may create a “helper” or “settings” function. This is just to make it easy to implement. Usually this will be an array of various items that need to be custom set. That will be noted with comments and in the instructions.

Complexity and Implementation

The more complex a customization, the more I HIGHLY recommend you start simple and build from there.

If possible, start with the example exactly as used in the instructions and/or demo code. Then make changes gradually, testing along the way.

You’ll be more likely to get a successful result with an exact duplicate of the example. You can always change it to get it to do what you need once you get it initially working. This may also help you understand better what the snippet is doing.

Best Practices

Always follow development best practices. In this case that means the following:

Use a development/test system if possible (i.e. don’t drop a new code snippet into your live production site unless you know you can back out of it immediately – and even then, that’s not a good idea).
Unless a piece of code is being noted as a bug patch or for a specific reason, never ever add code to the core plugin files. 99.9999% of the time, anything discussed on this site will be stored outside of the plugin and WordPress. Generally, this means store things in a custom plugin file or your (child) theme functions.php file.
Use a child theme for storing customizations.
Have a clean backup of the file that was working before you added your new custom code. Be sure that you can copy this backup to the web server should something go wrong with the new code. Generally, if you are working on a remote web server, that means keep a clean copy locally and have an FTP program you can transfer the file with. If possible, avoid using the WP theme editor in the WP admin panel for adding new code.

As always, if you run into problems or have questions, just let me know and I’ll be glad to help.