2012 New Year’s WordPressolution

WordPress Code Comments

It’s the New Year, a traditional time for resolving to make changes in our lives to better ourselves in the coming 12 months (and hopefully beyond).

Even though many of us stop going to the gym in about mid-February, there’s smaller changes that you can make in your life that are more manageable and realistic. Given that this blog is all about WordPress, it only seems fitting to write down a few “best practices” that you should try and adopt in order to make editing, managing and updating your blog a whole lot easier.

Stop using functions.php

It’s something that I mention frequently, but if ever you needed a kick up the bum to do this, now is the time. functions.php should be a file that is used by theme developers to define functions that manage and alter the way in which the theme appears and operates.

When we want to add or modify some functionality in our blog, we are often presented with snippets, which many people will tell you to put into functions.php, a habit which I want to help stop. This isn’t good because if you change or update your theme, any snippets you entered into functions.php will not be reflected in your new theme.

The better way to handle adding these code snippets is to use a functionality plugin. Do not be alarmed or overwhelmed; it’s actually very easy to create and you’ll be underway in about 10 minutes. Make the change now!

Edit theme and plugin files more appropriately

Once you start getting your feet wet in WordPress, you might start looking at your theme/plugin files and consider editing them to alter the appearance of your site slightly, whether it’s to add some social sharing buttons, or to add featured images to your posts.

There’s just a few tips that you should try and take on board which will help with managing your blog and keeping track of your edits:

Use comments to remove portions

Never, ever, ever delete code from a theme file or plugin file. Instead, use comments; this is a way of basically saying “ignore this bit”. If you’re editing a PHP file, you can comment out a section by using /* and */ to denote the beginning and end of your commented section. So for example, in the following section of code from my own functionality plugin, the snippet for delaying publishing to my RSS feed is disabled:

Make notes and explain your code

You should also use comments to make notes in your code on what each line does, or on what each section of code is for. In the example above, you’ll see that there’s a comment before each of the snippets that specifies what each snippet is for, for easy reference when looking at the code in future.

If you’re a theme or plugin developer, you should also use comments to explain your code, so that anyone (including yourself) looking at the code in future to either understand or modify it, can see what everything does. As an example, the following is a section of code from my SOUP widget, which shows upcoming posts to your readers:

As you can see, each line has an inline comment (marked by two slashes followed by the comment) explaining what it means, for easy reference during development and also for future modifications.

Your own resolutions?

What resolutions have you made for running/editing your WordPress sites over the next year? What would you tell others to do?

22 thoughts on “2012 New Year’s WordPressolution”

  1. IT Rush says:

    That’s a nice wordpressolution, mine.. I’ll just stick to minimizing the editing of some of the important codes in wp.

    1. Do you mean that you edit the core WordPress files at the moment? What are you going to change in how you edit files?

  2. About notes a comments. Heres my take on the subject.
    Don’t make notes and comments on obvious stuff. Like your examples.
    Commenting a variable by the name $posttype and saying its a post type is just a pointless comment. But having the variable name soup_number on a count type variable is just bad. Proper variable name would not require a comment.

    If you have a comment that says make links dofollow, theres no need to have a comment that says removes nofollow. Comments should be on how too use the function not explaining the name of the function.
    If you have to write a comment to explain what a function does the name is probably bad.
    If you need inline comments to explain stuff function is probably way to big, your scope variable names are crappy and most likely subfunctions should be extracted into separate functions. (I’m guilty of the big function bit, but since I’ve started using PHPStorm my refactoring is much easier and faster).

    My NYs resolution is to actually blog more both personal and professional. And almost always write testcases for my code.

    1. Hi Andreas,

      Thanks for your comment. I think there has to be a balance between explaining your code adequately and keeping your code trim. I cater more to beginners, and tend to think of myself as more of a beginner as well, and so tend to err on the side of caution, but perhaps an extra part of my New Year’s resolution needs to be being mindful of where I add notes. Looking back, I have to agree that adding a comment on a well-named variable is pointless and should lead me to be better at naming my variables.

      It’s great to hear input from a seasoned developer though, as I get a good idea of where things should be heading. Being entirely self-taught, it’s hard to catch on to the “best practices” that you would typically be taught under the guidance of an instructor or muse.

      Cheers, and Happy New Year!

      1. It was a mantra during my education. And its a good one. Makes life easier both for yourself and for others. I often feel that people don’t really give their stuff good explaining names. Its also a tellsign if your function does to much. createsNewUserAndAddsToListAndEmailsAdminAboutVerificationAndEmailsUserAResponseEmail =).

        1. I hear you man. So you had a formal education in programming of some sort then I can assume?

          1. Yep a few years doing a MSc in computer science ( could never get excited about the math and physics and so didn’t pass the exams= dropped it). Then got a BSc in Informatics and Systems Science (the aim was for the students to become Software Architects). Figured it would be good to have an official finished education and a title.

  3. My WordPressolution closely follows WP philosophy (http://wordpress.org/about/philosophy/). To make lean, clean and fast WordPress blogs!

    1. That’s a good resolution. I’d never seen that philosophy before, but it is very apparent that it was written by WordPress. It’s a very apt development philosophy and something that all developers would do well to adhere to.

  4. Tom J Nowell says:

    I’d delete code comments or ‘scars’, as the job of remembering old code is one Git/SVN is meant to handle. One can always mention in a comment that something used to happen, and provide a revision number/hash if it’s truly needed.

    Otherwise things just get bloated and unreadable

    1. That’s a fair point. I was thinking of it more from editing your own themes, where SVN isn’t available, but when developing plugins or themes on SVN, this is probably a good idea, and not something I had considered before. I haven’t worked with SVN nearly enough to be fluent with its ins and outs, but I’ve had a quick glance at revision history before and could probably fumble my way through it.

  5. Julian Medina says:

    Haha. Great resolutions! Last week I deleted a line of code of a plugin without commenting. Hopefully I’ll get better if I opt to learn PHP and become good in programming!

    1. Well, it’s a learning curve and that’s why I’m here. We’ll all make mistakes, just learn from them and proceed.

  6. Frank Bowes says:

    Hey Dave, a great post as usual. I’ve seen these types of comments in themes, and I always look for them when purchasing a new theme. For dunces like me it makes life so much easier.

    1. Yeah, a well commented and documented theme can make configuration and edits a whole lot easier.

  7. Ray says:

    Are you commenting code in your wordpress dashboard editor or are you editing files with your hosting file manager of ftp client? Reason I ask is I have tried commenting code in the wordpress dashboard editor in the past. Sometimes it works, other times it errors out. I don’t know if it is adding some space or whitespace maybe or what the deal is.

    1. It depends. I use all three, depending on what I’m doing. I haven’t experienced the WordPress editor adding any white space though. It’s worked out just fine for me, same as if I was using cPanel or FTP.

  8. Reima says:

    My resolution for this year is to deeper understand WP structure and learn OOP, because right now my skills is not so good – i could not write my own plugins or thems, could not even imagine how it works, despite the fact that I am not a newby with php and wordpress. Your blog is full of info to train my skills, thanks for that and, please, keep writing!

    1. Those are some good resolutions. I still consider myself a newbie too, and you’ll get there step by step.

  9. Tory says:

    You actually mentioned a few pet peeves of mine here! :) Anyways, my goal at the start of this year was to create my first wp plugin. There are a few problems I’d like to solve and I feel others might benefit from it, as well. Unfortunately, it’s just over half way through the year now and still have yet to start… Always next year right? ;)

    1. Yeah, sometimes you just need to dive in though. Once you start writing the code, it just falls together and you want to keep going to see it get completed and working!

  10. Jesse Veluz says:

    WordPress Resolution is such a great idea Dave.

    My WordPress resolution is to start taking advantage of WP Child Theme. In my last year working with WP, I have been into bad habit of modifying codes straight from the theme files. It was horrible to know that all your changes get lost as soon as the theme upgrades. Using child theme will save you from all these losses.

    By the way, using functions.php file is a great idea IMO since it will give you control over your wordpress site. For as long as you are using child theme. You don’t have to worry about losing your modifications. Though I agree, it’s best if you learn to use the functional plugin.

Leave a Reply