Programming Style Guide

Since toolbox is a project that receives contributions from multiple people from various programming backgrounds it is important to be aware of style conventions and usage of them.

Use an editor that supports ESLint and EditorConfig

The majority of the programming style we require is defined and enforced through the configuration of these two tools. So the easiest way to make sure that you follow them is by using an editor that supports both. Here is an example on how to set up Visual Studio Code, you are of course free to use any other editor as long as it either supports ESLint and EditorConfig or you make sure the specified styles are followed in some fashion.

When you commit code to this repository or make a pull request the code will automatically be checked for compliance with these guidelines.

ESLint

The majority of our javascript styles are enforced through ESLint.

To see what rules are configured you can have a look at the project .eslintrc.json file.

.editorconfig

In addition to ESLint we use EditorConfig to enforce some general style related things. Most obviously tabs which we have defined as 4 spaces. Also see .editorconfig

Javascript

jQuery variables should be preceded by $

You should clearly mark variables which contain jQuery objects by preceding the name with "$". For example, in Mod Button, we have $popup, which is a jQuery object referencing the current .mod-popup object.

Objects should only be converted jQuery objects once.

Bad:

    foo.each(function() {
        $(this).jqueryBar();
        $(this).jqueryBaz();
        this.nativeBar()
    });

This converts the object to a jquery object twice.

Good:

    foo.each(function() {
        const $this = $(this);
        $this.jqueryBar();
        $this.jqueryBaz();
        this.nativeBar();
    });

JSDoc

We use JSDoc to document helper methods and constants in Toolbox's code. For consistency, we use these guidelines when writing JSDoc tags:

• The description should be the first thing
• Use @function and @constant without a name to document the type of namespace members
• Lines should end somewhere between columns 80 and 120 (you can set up rulers for this in many editors)
• Include expected types for all parameters and the return value
• Only omit @returns if the function does not return a value
• Add descriptions for parameters and return values unless they are self-explanatory
• Functions which take an options object should have all possible options documented
• Denote optional parameters as [foo], and default values with [foo=default]
• Prefer periods at the end of member descriptions, but never at the end of parameter or return value descriptions

For example:

/**
 * Squares a number.
 * @function
 * @param {number} num
 * @returns {number}
 */
function square (...) {...}

/**
 * Greets a user.
 * @function
 * @param {object} options
 * @param {string} [options.greeting = 'Hello'] The greeting to use
 * @param {string} options.name The user to greet
 * @returns {string} The greeting string
 */
function greet (...) {...}

/**
 * True if the user is on new Reddit, false otherwise.
 * @constant {string}
 */
const isOnNewReddit = ...;

HTML & CSS

Relative urls in CSS

When there is a need to reference a external resource (large images) don't use relative urls. They cause issues in both chrome and firefox at times. Just use the absolute https url, non encrypted urls are not allowed.

DOM element class & ID naming.

When introducing elements to the dom always give them class names or IDs starting with tb-. This avoids conflicts with native reddit elements that might be named similarly, other extensions and in general makes it easier to see what elements are added by toolbox.

When you need to store variable in elements use the data- attribute.

Example:

      <span class="tb-whatever" data-variablename="your important data">hi!</span>