The comments on this post have been closed. Please check out this update for more information.
One of the things that open source advocates always claim is that you should give back to the software that has given you so much.
For some, this comes in the form of code, others this comes in the form of bug testing, tracking tickets, writing documentation, or something along the lines thereof.
Only occasionally do I discuss JavaScript on my blog, but it’s actually one of my favorite languages. In fact, there was a time in my career where I was looking to pure JavaScript applications.
Preferences change, though.
Last year, I made my first contribution to WordPress Core, which was exciting, and I’m currently working to edit the Plugin Developer Handbook with a group of a developers far more talented than I am (so I’m getting to learn from their work for free ;).
Anyway, one of the things about the WordPress Coding Standards that’s always seemed incomplete to me is how little it focused on JavaScript. It provides guides for PHP, for HTML, and it even has a stub for CSS, but there’s nothing in the Codex about JavaScript.
For the past few months, I’ve been working on exactly that. Today, I contributed to the WordPress Coding Standards by introducing the WordPress JavaScript Coding Standards.
The WordPress JavaScript Coding Standards
I’ve been working on this off and on since October or November of last year and finally published it to the Codex this morning.
The Standards include the following topics:
- Braces
- Quotations
- Whitespace
- Naming Conventions
- Constructors
- Filenames
- The `var` Keyword
- Operators
- Objects
- Arrays
- Conditionals
- Loops
- jQuery
- …and more
For those of you who have followed my blog for a while, you also know that I’m a fan of JSLint. Because I view that more as a personal preference, I left it and its associated conventions out of the standards for now.
As I see it, this is purely a 1.0 of the documentation. With such rich possibilities with jQuery and Backbone, I’m sure the documentation could use some revision, so I’d love to see the documentation grow.
At any rate, I’m proud to finally have something official in the Codex that provides guidelines for writing quality JavaScript that will make our themes, plugins, and other tools a bit easier to follow and maintain.
Now to refactor all of those old source files ;).
But It’s Not Done!
The truth is, this topic will be something that’s constantly evolving so as much as I’d love to see feedback from you guys, I’d love to see contributions to the articles even more.
So please feel free to improve upon what’s there and let’s create the most solid documentation for JavaScript that we can.
Wondering if it wouldn’t be a wise thing to give wp_localize_script() a nod when discussing strings? Should be a rare (if ever) occurrence for a plugin to actual incude a string in the way outlined in the docs.
I think this is a smart move. I mean go back and edit this or not. Right now, there are two ways to tackle it:
Use the current way of localizing JavaScript strings by mixing JavaScript in your templates as outlined in the Codex
Leave the strings in line in the JavaScript and leave a note to translators.
Historically, I’ve done the second option because I hate mixing languages when I don’t have to, but it comes at the cost of documenting the JavaScript for translators to look out for it.
This particular thing would be a fun discussion, though :).
It’s entirely possible I haven’t had enough coffee today, I’m only on my first cup – but I don’t think I’m totally picking up what you’re putting down.
Here’s how I envision the best practice to be (in gists) –
1. Localize your script, leaving notes to translators as necessary.
2. Reference the object containing the internationalized strings in JS.
Boom. Separation of PHP from JS. 100% localizable. Translator notes included, if necessary. Pandas around the world rejoice.
But again, I’m sure I’m missing something in your comment :)
Don’t think you’re missing anything. This is the right way to do it and is also the way core deals with strings in JavaScript as well.
You should never have an untranslated string in a plugin, theme, or core patch JS file.
Yes sir – my fault for not being clearer (I should’ve taken into account the lack of coffee-quota ;)).
Option 1 is the one I normally use.
You + coffee = big brained code, Sainton :).
Thank you, sir!
Indeed!
Nice addition Tom and I definitely think it was needed. Thanks for helping everyone out.
Of course! But I see this as just getting the ball rolling. It’s a community effort, you know? Hopefully others will add to it and refine it.
Thanks a lot, Jonathan. Really glad to help and hope that this will spur additions and more improvements to be made over time.
Awesome. Did I misunderstand or shouldn’t all conditional statements look like they should in PHP? So:
if ( a === b ) {goNuts();
}
and not :
if( a === b ) {// etc...
}
I’ve also seen:
if ( a === b )drinkBeer();
else
washHair;
In core js code. Is this not ok?
Mega thanks for the documentation! Love the WP style :D
Oops, all my indentation got stripped out!
Ah, yes. Nice catch! That’s something that should be edited.
Additionally, I always include brackets. I have my own reasons for it, but I also think that the potential to create unreadable code is simply too high especially with the variety of editors that we have available that always handle spaces and tabs differently.
You may think you know what the original developer meant, but maybe not. It’s just one of those safeguards that I follow to make sure I’m as clear as possible.
This has been needed for such a long time!
Thanks for taking the time to put forth the effort and get this going.