When sharing WordPress related code snippets, I can haz standards please?

I love WordPress. Just absolutely love it. One of the things I love especially is how you can alter the output by adding just a small snippet of code. Turns out I”m not the only one who loves doing that because when you”re googling any given WordPress related subject, the pure amount of hits on Google can be overwhelming. I love how you can easily copy any of those snippets of code and put “em to use on your site.

But, I believe there”s something missing with all those snippets, at least in most cases. Two things: proper WordPress coding standards and inline documentation. Of those two articles on the Codex there are a few things that you should know about – whitespace, indentation & DocBlocks.

Here’s why. Not only does it make sense to adhere to WordPress coding standards when you’re building code that’s supposed to work with WordPress, but it also makes your code look good. Using function-level DocBlocks makes so much more sense when you think about it. When sharing your snippet – be it long or short – with tags like @author and @link, for example, make a few things a bit more obvious. Specifically, who the author is of the code, copyright information and the url explaining the snippet a bit more (most likely the article you have just written for that snippet). Code standards help especially in these two regards:

1. Consistency between the code you your readers will have in their projects, and the code snippet you”re giving them – no odd coding styles to have to reformat.
2. Consistency when different developers work on the same bit of code – no time spent having to learn someone else”s coding style.

Consider the following two examples:

Before:

After:

Mind you, this is not the most complicated function ever built and could thus probably do without the comments, but I wanted to get a point across here, remember? You”ll see I”ve also prefixed my functions properly, but I didn”t need to point that out to you guys, right? You all were obviously already doing that ;). I am by no means an expert on these matters, but I am inspired by Gary Jones – who helped write this post and whose expertise in this matter I hold in very high regard. Seeing him work on updating the code Genesis uses to the proper standards has inspired me to write this post.

So how about it? I would love to see sites like WPRecipes, WP-Snippets and WPBeginner adopt this style of writing code. I mean, isn”t this where the whole Code is Poetry starts? Also, consider pasting snippets on Github”s gists. Kinda like Pastebin, but cooler in my opinion. Your snippets are automagically turned into a Git repository. Making collaboration and code improving easier to do.