Contributing
All our development on Plupload goes through GitHub, if you wish to contribute, you need to learn how GitHub works first of all. There are a lot of help videos and similar that can help you get started.
Coding standards
In general, if you look at the code, and feel the need to reformat tabs, indenting, brackets etc, please stop, your code will not be merged into the Plupload master if you start to reformat everything just cause that is the way you have learned it, we consider this an insult to the way we code.
You are unique, just like everyone else
We have a certain style of coding, a fairly common style, but we all have our personal preferences, we expect you to respect that and fall into line with the rest of the code base when you help us develop this software.
Example
Let us start of with an example, function declarations follow the unix convention.
/** * Forces anything into an array. * * @method toArray * @param {Object} obj Object with length field. * @return {Array} Array object containing all items. */ toArray : function(obj) { //<-- Start on the function declaration line, not on next line. var i, arr = []; //<-- clear, short but self-describable variable names. // Observe spacing between items in the for statement for (i = 0; i < obj.length; i++) { //<-- Needed for jslint arr[i] = obj[i]; } //<-- Needed for jslint return arr; },
This is a simple function ripped out from the middle of the code, observe the indentation and structure logic. We usually do not have brackets for single line loop/if statements, but they are required for jslint. Also observe the simple comment structure, first a short description of what the method does, the method name and then @method, @param, @return. If you have more than 1 param, just add another line.
Indentation
Tabs should always be used for indentation, empty lines or end of lines should not contain any spaces or tabs.
Comments
In general, there is no such thing as "to much comments", but keep them short and to the point, it should be a description of the code, not a story about the code. Comments gets stripped out in the build process, so it will not impact the size.
Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at the section of code and think "Wow, I do not want to try and describe that", you need to comment it before you forget how it works.
Expressons
- Use parentheses liberally to resolve ambiguity.
- Using parentheses can force an order of evaluation. This saves the time a reader may spend remembering precedence of operators.
- Don't sacrifice clarity for cleverness.
- Write conditional expressions so that they read naturally aloud.
- Sometimes eliminating a not operator (!) will make an expression more understandable.
- Keep each line simple.
More guidelines
If something is unclear or not described properly, check out the source for yourself, and please be aware of the minor differences as well, such as how we code spaces between variable name, operator and value, or the spacing between items in function names, if/else statements or conditional expressions.
{position : 'absolute', width : '100px'}
if (this.state == plupload.STARTED && fileIndex < files.length) {
Following these simple guidlines will reduce the load for us and increase the chance of your code ending up in the main code base.
Check out the code on GitHub for more beautiful source!