5 things to know before starting to design a WordPress theme

Posted on September 22, 2010

With hindsight, there are things that are definitively not obvious to me when I started to design my first WordPress theme, things which are not very well explained in the official documentation. To begin, be aware that WordPress theming is everything but beautiful coding: no OOP, no MVC, no respect of coding good practices, nor even of common sense sometimes… I’ve learnt these things at my expense, so I’m now going to warn you from the beginning so that you don’t get the cooling effect that I got.

#1 You can forget about MVC

If there is something that totally had a cooling effect on me, it’s how WordPress is coded… When you use it and you never need to write something specific, never mind how it’s coded under. But when you have to get your hands on it, be ready to forget what is a beautiful code: it’s pure procedural style. A get_header() function for the first part of your page, a get_footer() for the last, and in the middle you have the content of your page.

#2 Functions have meaningless names

I know I’m a little picky when it comes to coding. I LOVE beautiful code and I have a profound respect for good practices. But honest, can you guess what does the “the_title()” function do? Does it write the title of a post, does it return it as a string, or something else?.. Well actually the good answer is it writes the title of a post.

But then why the fuck does the “get_search_form()” also writes the search form instead of returning it? What’s your definition of the verb “get”, WP guys?

Ok I’m picky? Here is another exemple to show you how inconsistent and illogical it is. Would you guess the meaning of the “the_post()” function? No, it doesn’t write the body of the post just like “the_title()” writes the title. No! Too easy! Little player… What it really does is, according to the PHPdoc: “Iterate the post index in the loop.“. It’s full of meaning, isn’t it?

#3 Most of the functions don’t return anything, they write content

In your templates, you will use WP built-in fonctions to display your data. the_title() writes the title of a post, the_content() writes the body, the_tags() writes the tags, and so on … Unfortunately it writes those data, instead of returning them. Honest, what’s the most difficult piece of code to write:

<?= the_title() ?>


<?php the_title() ?>

Answer: none of them. So why do you echo content in your functions instead of returning their values, and don’t let the “view” (oh sorry, no MVC with WordPress…) I mean let the theme decide to write it right away or to do extra processing (such as adding some tags, attributes, CSS classes,  … or anything!)

Be ready to have fun with ob_* functions sometimes 🙂

#4 There is no template for comments

There are templates for almost everything in WordPress: a template for the index page, for a single post, for search results, for tag pages… But no template for comments? Uh I don’t get the point there… There is a work around technique though, that uses a callback function to write the comment HTML, but honest it’s dirty.

#5 You can’t get the number of posts easily

Maybe there is a technical good reason to that, but honest it was a pain when I was working on it: when you display many posts on your page, you will have to use a While loop, no way otherwise.

Alright, whatever the loop as long as it does the job, will you say? It does the job yes, until you need to know the total number of posts on your page, or you want to deal with the previous/next post, or want to do something special with the last post, like applying a special CSS style just to it.

For and Foreach loops are not monstrous you know WP guys, we’re not afraid of using them ^^ And it gives much more information, such as the cardinality of the posts in advance.

Hopefully you can still trick to get those information, by using SQL queries and so on, as it’s explained in many forums … But again, it’s quite a dirty way to do it.

Ok WordPress is dirty, then what?

Then it hurts my feelings! Because I can’t stop using it because WordPress rocks for other reasons. I was just surprised that WordPress, the leader for blogs in the world, was technically that bad thought. But hey, that’s the game and I did my WP theme anyway because I needed it… Now it’s done I hope I won’t have to get my hands on it too soon.

About the author

Cyril Mazur is a serial web entrepreneur with experience in various fields: online dating, forex & finance, blogging, online advertising... who enjoys building things that people like to use.


  1. Dan Grossman
    on September 22, 2010
    "Most of the functions don’t return anything, they write content"

    For every such function, there is another function that returns the string instead; the functions you are using (the_title) are just wrapping those. Use get_the_title, get_the_content, etc. if you want.

    "to do extra processing (such as adding some tags, attributes, CSS classes, … or anything!) Be ready to have fun with ob_* functions sometimes"

    There are hooks and filters for that; you're not supposed to be doing that processing in the template.

    "There is no template for comments"

    There is; create a comments.php file and loop through $comments. You only do the callback if you use the relatively new WP function that outputs a threaded list of comments for you.
  2. Cyril
    on September 22, 2010
    Hi Dan,

    1° I didn't know about the get_* functions, my bad ^^

    2° Do you know how to do this extra processing elsewhere without forking the WordPress core? I was really just focusing on the theming aspect of WordPress, but maybe there is something else to do, like writing a sort of framework to support the theme? Anyway point 1° solves point 2° in my case :)

    3° You're right again, I didn't know about the $comments variable either. I must have missed something in the doc or ..? But I still deplore the lack of consistency there.
  3. Joel Sutherland
    on September 22, 2010
    My company hates WordPress style theming. In fact, many of the design decisions we made on our product were to address this pain point. There are so many details to remember that the process of creating a theme becomes about Wordpress rather than about front-end web code.

    We use Twig as a templating language and expose our entire data API so there isn't a massive set of functions to learn. Here is an example of how to list the latest posts:

    {% for post in hifi.get({'type':'post','orderBy':'-publishedAt'}) %}
    {{ post.title }}
    {% endfor %}

    This keeps the process of creating a theme mostly about HTML/CSS because it dramatically reduces the specific information that you need to know about the platform itself.
  4. weston deboer
    on September 22, 2010
    #1 Isn't WordPress a MVC itself.

    #2 When WordPress was started many a years ago, they did come up with some wonky names for things. But as time has gone on they realized this and didn't want to break anything. Themes from the first version of WordPress will work on the latest version of WordPress. Making upgrading seamless, unlike other cms.

    #3 See http://codex.wordpress.org/Template_Tags/get_the_title

    #4 http://codex.wordpress.org/Function_Reference/comments_template

    #5 Doesn't make sense. You know that 10 posts are being pulled. There are ten.

    I believe this post is link baiting
  5. Cyril
    on September 22, 2010
    Looks promising Joel. For what I can read, Twig isn't designed for WordPress at the main purpose, do you use something specific to interface it to WordPress, an open solution or your own?
  6. Ariejan de Vroom
    on September 22, 2010
    I got the same issues with WordPress. It's the same with plugins as with themes. Besides, when you install 5+ plugins, your blog get so slow you can make two cups of coffee before it loads.

    Anyway, I switched to Toto some time ago, caching it with Varnish and it's blazingly fast. It uses HAML for templating and it's simply awesome. Oh, and it's ruby, not PHP.

    Read about it here ( http://aj.gs/24 ) and here ( http://aj.gs/2C )
  7. Cyril
    on September 22, 2010
    Hi weston,

    #1 And then it's a shame isn't it?

    #2 What has been done before cannot be undone so easily, I agree... An alternative solution can still be envisaged, like a brand new framework for theming and a possible legacy mode for old ones? Joomla does it for instance.

    #3 You're right, shame on me for having missed this point.

    #4 My bad, again.

    #5 You know that 10 posts are being pulled unless there is less (for example the archive.php page, do you write at least 10 posts a month?), or the last page in your navigation.

    It's the first time I post a link on hacker news, true, and it even DDOsed my server after some minutes ^^ But I didn't write this post on purpose, as you can see (or not) I've just renewed the theme of my blog and I wanted to share the frustrations I had doing it, as it was still fresh in my mind.

    Thanks for giving your opinion though
  8. Peter Westwood
    on September 23, 2010
    I'm sorry you had such a bad experience.

    Maybe you should have spent more time reading the documentation and understand how WordPress works.

    Our users find it easy to use and reliable.

    Just because it looks different from what you are used to doesn't make it wrong!

    If you find any bugs please let us know - http://core.trac.wordpress.org

    If you can include a patch as well it is always well received!
  9. Cyril
    on September 23, 2010
    Hi Peter,

    I agree, of course I cannot expect everything to work the way I like and I'm used to. And I already got my post was wrong in some points, and could have looked less ridiculous if I had read the doc more carefully.

    However I still think that using old fashioned coding practices nowadays is not acceptable, and especially for a huge project like WordPress. I take care of my code a lot when I know other people are to use it. Inconsistency is not a bug, it's just a bad way to do things.

    I want to say I like WordPress though (as you can see, I'm using it!), honest it rocks ... until you want to dive into the code!
  10. Richard
    on October 23, 2010
    Hi Cyril

    Thanks for your great post and the broad gist of which I echo (php joke?).
    WordPress I find quite hard to develop with and help very hard to find which means I spend lots of time trying to get code to work rather than using my websites!
    However WordPress undoubtedly is a feature rich CMS and these features are great to use when you can get them working! It is great that it is highly customisable even though it can be a great pain getting these customisations to work!

    (BTW Cyril my screen size is small &amp; I do not see the whole width of your page).

    Many thanks for your post &amp; best wishes
  11. Christof Coetzee
    on January 3, 2011
    I fully agree with Cyril, there is a right and wrong way to do things.
    I've been coding PHP for the past 12 years and on Zend Framework (MVC) for the past 3 years, hence believe I have a license to say: Wordpress code base is very old school and dirty.
    I also understand is too late and Wordpress cannot change anything at this point unless they start a new MVC version (trunk), which will not support any of the old plugins or themes.
    Wordpress can do this as part of their project lifecycle, the same as PHP has done with their version 4-6, and then ultimately discontinue support/development for the "old" version of Wordpress.
    This just emphasize again that planning and vision is vital.

Leave a Reply