This document describes the code conventions used in JavaScript code written by the Splunk Seattle office, notably in the Web Framework and JavaScript SDK projects. It is intended to guide developers to a common style and reduce the number of style-related nits received in code review comments.
Although this is a JavaScript guide, a number of recommendations here are language independent.
When working in an existing source file that is consistently styled in a particular way, be consistent with local style. This takes precedence over all other guidelines.
If local style is inconsistent but a dominant local style prevails, use that style. If there is no clear dominant style then insert new code using the style of this guide.
This set of conventions is a set of guidelines, not absolute rules.
For example if a guideline exists for a particular rationale that does not apply in a particular situation, the guideline may not apply.
Other guidelines with no particular rationale exist mainly for consistency (such as the choice of 4-space vs. 2-space indentation). By analogy with the real world, there's no particular reason why the cold water faucet is on the right in the USA, although it is very useful that it is consistently there. Otherwise you might burn yourself should a rouge sink-maker put the hot water on the right instead.
If a guideline needs to be ignored in a particular case, consider adding a comment to explain why, usually in the form of a NOTE flag comment. (Flag comments are described below.)
-
Code is easiest to read in a top-to-bottom fashion, as one would read a book. Therefore top-level functions should be arranged before lower-level functions. Functions should call downward.
Additionally logically related methods should be grouped together. By contrast the use of unmeaningful orderings like a strict alphabetical ordering is discouraged.
Yes:
var BaseSplunkView = Backbone.View.extend({ constructor: function(options, settingsOptions) { ... this.configure(); this.initialize(); ... }, configure: function() { ... }, initialize: function() { ... }, bindToComponentSetting: function(settingName, fn, fnContext) { ... }, bindToComponent: function(id, fn, fnContext) { ... }, unbindFromComponent: function(id, fn, fnContext) { ... }, ... });Above, the methods are conceptually bound together in the structure:
- constructor
- configure
- initialize
- (binding methods, commonly called in initialize)
- bindToComponentSetting
- bindToComponent
- unbindFromComponent
- (other methods that apply after initialization)
-
...
-
- constructor
-
Exception: There are some technical circumstances where calling upward is required, such as the final return statement in an AMD-style define clause. These circumstances should be considered the exception rather than the norm.
Yes:
define(function(require, exports, module) { var _ = require('underscore'); ... var BaseSplunkView = Backbone.View.extend({ ... }); return BaseSplunkView; }); -
Exception: Many developers are not familar with the details of hoisting in JavaScript, so it should be considered a technical limitation that nested local functions must call up.
Yes:
function formatMessageElement(message) { // NOTE: Does not handle characters outside the Basic Multilingual Plane. var isValidChar = function(charCode) { return charCode >= 32; }; var isValidString = function(s) { for (var i = 0; i < s.length; i++) { if (!isValidChar(s.charCodeAt(i))) { return false; } } return true; }; return (isValidString(message)) ? "<message>" + message + "</message>" : "<message/>"; }No:
function formatMessageElement(message) { return (isValidString(message)) ? "<message>" + message + "</message>" : "<message/>"; function isValidString(s) { for (var i = 0; i < s.length; i++) { if (!isValidChar(s.charCodeAt(i))) { return false; } } return true; }; // NOTE: Does not handle characters outside the Basic Multilingual Plane. function isValidChar(charCode) { return charCode >= 32; }; } -
However if you were to pull the nested local functions out to be siblings instead, top-to-bottom ordering still applies:
Yes:
function formatMessageElement(message) { return (isValidString(message)) ? "<message>" + message + "</message>" : "<message/>"; } function isValidString(s) { for (var i = 0; i < s.length; i++) { if (!isValidChar(s.charCodeAt(i))) { return false; } } return true; }; // NOTE: Does not handle characters outside the Basic Multilingual Plane. function isValidChar(charCode) { return charCode >= 32; };
Individual methods and functions should be organized such that each does one thing and does it well.
Nevertheless a method may perform multiple discrete low-level actions when performing a higher-level task. Actions that takes a few lines of code are good to visually separate from adjacent actions with a empty line. One-line actions do not benefit from separation.
Example:
_configureBindingForPush: function(propName) {
var binding = this._bindings[propName];
if (!TokenUtils.isToken(binding.template)) {
// This property's template is not presently bound to a
// single token. Therefore there is no token that can
// be pushed to yet.
return;
}
// Forward value changes to solitary token in template
var that = this;
var listener = function(model, newValue, options) {
that._pushPropertyValue(propName);
};
this.listenTo(this, 'change:' + propName, listener);
// Save listener for later removal
listener.dispose = function() {
that.stopListening(that, 'change:' + propName, listener);
};
binding._listeners.push(listener);
},
Many of the paragraphs in this example also have leading comments, which are useful.
Paragraphs that grow too large are good to extract to private methods.
Adjacent methods, classes, and paragraphs should be separated by one blank line to make them easy to distinguish.
Yes:
var TextInputView = BaseInputView.extend({
initialize: function() {
...
},
getValue: function() {
...
},
setValue: function(value) {
...
}
});
No:
var TextInputView = BaseInputView.extend({
initialize: function() {
...
},
getValue: function() {
...
},
setValue: function(value) {
...
}
});
-
There should not be blank lines at the beginning or end of a block.
Yes:
var TextInputView = BaseInputView.extend({ initialize: function() { ... } });No:
var TextInputView = BaseInputView.extend({ initialize: function() { ... } }); -
There should never be two blank lines in a row.
-
There should not be extra blank lines at the beginning of a file. An extra blank line may exist at the end of a file to accomodate environments that expect a trailing newline for every file.
-
Spaces only. No tabs.
-
JavaScript files use 4-column indentation.
-
JSON files use 4-column indentation.
-
HTML may use either 4-column or 2-column indentation. Prefer 4-column indentation if there is no local preference to allow easy mixing of standalone JS with HTML that includes embedded JS.
Tabs are avoided because they are interpreted differently by lots of different tools. In particular some tools may assume a tab width of 8 while others may assume a width of 4. For consistent behavior everywhere, only spaces are a safe bet.
To make this guideline easy to follow, please configure your editor to automatically convert inserted tabs to spaces. But preserve the tab-ness of any tabs that already exist in the file. For Sublime:
// When tab key is pressed, insert spaces. Leave preexisting tabs alone.
"translate_tabs_to_spaces": true
Note that a few file types require real tabs in certain circumstances. Makefiles in particular.
-
Avoid lines longer than 80 columns.
-
Strongly avoid lines longer than 100 columns unless there is a specific technical reason.
Long lines make it difficult to have many documents onscreen at once. Typographically they are hard to read. They also interfere with Crucible side-by-side diffs because each side of the diff has its min-width set to the length of the longest line in the file under review.
To make this guideline easy to follow, please configure your editor to display a vertical rule at the 80 and 100 column positions. For Sublime:
"rulers": [80, 100]
-
When breaking a statement on multiple physical lines, the second and subsequent lines should be indented a single level greater than the first line.
-
Break lines after operators, not before.
Yes:
complexical = supercalifragilisticexpialidocious + floccinaucinihilipilification + antidisestablishmentarianism;No:
complexical = supercalifragilisticexpialidocious + floccinaucinihilipilification + antidisestablishmentarianism; -
Exception: The ternary operator (
? :), when broken on multiple lines, should break before each operator. The conditional expression should also be parenthesized:complexical = (boris === natasha) ? floccinaucinihilipilification : antidisestablishmentarianism; -
Multi-line expressions may optionally be surrounded by parentheses to emphasize the unity of the expression.
Okay:
complexical = (supercalifragilisticexpialidocious + floccinaucinihilipilification + antidisestablishmentarianism); -
Break lines after spaces when breaking string literals.
Yes:
complexical = 'Lorem ipsum dolor sit amet, consectetur adipiscing ' + 'elit. Sed et auctor magna. Nullam interdum lobortis lectus eu ' + 'tempus. Etiam suscipit vulputate sollicitudin.'No:
complexical = 'Lorem ipsum dolor sit amet, consectetur adipiscing' + ' elit. Sed et auctor magna. Nullam interdum lobortis lectus eu' + ' tempus. Etiam suscipit vulputate sollicitudin.'
In general:
-
For multi-line blocks, the opening brace should hang off the end of the line.
-
The closing brace should be indented to the same level as the line on which the open brace appears.
-
Statements that continue after a closing brace should preferably continue on the same line as the closing brace.
Preferred:
if (foo === bar) { ... } else { ... }Okay:
if (foo === bar) { ... } else { ... }No:
if (foo === bar) { ... } else { ... }
Exception:
-
Block statements whose header needs to be broken on multiple lines should move the open brace to the next line, at the same indentation level as the header.
Yes:
if (floccinaucinihilipilification && antidisestablishmentarianism) { findDictionary(); }No:
if (floccinaucinihilipilification && antidisestablishmentarianism) { findDictionary(); }This creates additional vertical space that visually separates the multi-line header from the first statement in the block. Without this space there would be a false visual grouping between the header lines and the block lines.
(Much of this section is shamelessly ripped from PEP 8 and adapted for JavaScript.)
Avoid extraneous whitespace in the following situations:
-
Immediately inside parentheses and brackets.
Yes: spam(ham[1]); No: spam( ham[ 1 ] ); -
Immediately before a comma, semicolon, or colon:
Yes: if (x === 4) { console.log(x, y); } No: if (x === 4) { console.log(x , y) ; } Yes: spam({ eggs: 2 }); No: spam({ eggs : 2 }); -
Immediately before the open parenthesis that starts the argument list of a function call or function literal:
Yes: spam(1); No: spam (1); Yes: exports.createServer = function(port, host) { ... } No: exports.createServer = function (port, host) { ... } -
Immediately before the open parenthesis that starts an indexing:
Yes: dict['key'] = list[index]; No: dict ['key'] = list [index]; -
More than one space around an assignment (or other) operator to align it with another.
Alignment is difficult to maintain, particularly in the presence of rename refactorings, and therefore should be avoided in general.
Preferred:
x = 1 y = 2 long_variable = 3Avoid:
x = 1 y = 2 long_variable = 3 -
Exception: If there is duplication on each side of multiple assignment operators in a paragraph, alignment may be used to emphasize this.
Okay:
this.specialize = utils.bind(this, this.specialize); this.apps = utils.bind(this, this.apps); this.configurations = utils.bind(this, this.configurations); this.indexes = utils.bind(this, this.indexes);Okay:
var Context = require('./context'); var Http = require('./http'); var Async = require('./async');
Use single spaces in the following situations:
-
After keywords that begin a statement.
Yes: if (i > 0) { ... } No: if(i > 0) { ... } Yes: return (i == 42); No: return(i == 42); -
Immediately inside braces.
Yes: if (x === 4) { spam({ eggs: 2 }); } No: if (x === 4) {spam({eggs: 2});} -
Immediately before the open brace of a function literal:
Yes: var isChoiceView = function(v) { return v instanceof BaseChoiceView; }; No: var isChoiceView = function(v){ return v instanceof BaseChoiceView; }; -
Immediately after commas and colons:
Yes: chart.set({ seriesColors: [0xBF3030, 0xFFE800] }); No: chart.set({ seriesColors:[0xBF3030,0xFFE800] }); -
Around binary operators:
Yes: for (int i = 0; i < cars.length; i++) { ... } No: for (int i=0; i<cars.length; i++) { ... }However if operators with different priorities are used, consider removing whitespace around the operators with the highest precedence. Use your own judgment; however always have the same amount of whitespace on both sides of a binary operator.
Okay:
i = i + 1; submitted += 1; x = x*2 - 1; hypot2 = x*x + y*y; c = (a+b) * (a-b);
Other recommendations:
-
Prefer one statement per line.
Yes:
if (foo === 'blah') { do_blah_thing(); } do_one(); do_two(); do_three();Avoid:
if (foo === 'blah') do_blah_thing(); do_one(); do_two(); do_three(); -
Avoid using parentheses with
returnstatements if the meaning is clear without them:Yes: return x; No: return (x); Okay: return (x == 1); // parens here avoid an initial misreading as "return x"
Trailing whitespace on non-blank lines should be avoided. For blank lines it is preferable to leave whitespace up to the logical indentation level. For example:
/**
.*.Marks the specified property as being push-enabled.
.*.
.*.Due to this definition, [...]
.*/
enablePush: function(propName) {
....if (this._isPushEnabled(propName)) {
........// Already push-enabled
........return;
....}
....
....this._pushed_properties.push(propName);
....
....// If binding already exists, push-enable it
....if (this._bindings[propName] !== undefined) {
........this._configureBindingForPush(propName);
....}
},
Leaving whitespace up to the indentation level makes it easier to insert new code around a blank line and easier to navigate.
Sublime's default settings automatically remove spaces on blank lines that are newly inserted. To avoid this use the setting:
// Do not remove whitespace on newly inserted blank lines when cursor is moved away.
"trim_automatic_white_space": false
Some editors can be configured to autoformat documents upon save. For example newlines can be automatically appended to the end of files that lack a trailing newline. Or trailing whitespace on lines can automatically be deleted.
Such autoformatting should be avoided. It generates unnecessary extra diffs, making code review more difficult. And the autoformat algorithm may clobber intentional elements of the local style, such as certain uses of trailing whitespace.
String literals should prefer single quotes (') over double quotes ("). It is easier to type and encourages the use of double quotes in output messages which matches English typographical convention. It also makes it easy to use double quotes in SPL searches, which is required by the search language.
Yes: console.warn('SelectView declares "value" property with undefined value.');
No: console.warn("SelectView declares 'value' property with undefined value.");
Yes: context.on('search:start', function(job) { ... });
No: context.on("search:start", function(job) { ... });
However if you need to use single quotes in a string you can still use double-quoted strings in that case.
The former operators make a strong type comparison, which is the equality semantic you usually want.
Yes:
var a = 0;
if (a === '') {
console.log('winning');
}
No:
var a = 0;
if (a == '') {
console.log('losing');
}
Unfortunately there are no strong equivalents for the comparison operators <, <=, >, >=.
Only quote keys when your interpreter complains. In particular keys that are not alphanumeric or those that collide with JavaScript keywords (ex: default). This makes brevity the default.
Later versions of JavaScript allow keywords to be used directly as unquoted keys but many older browsers will choke.
Yes:
var foobar = {
foo: 1,
bar: 2
}
No:
var foobar = {
'foo': 1,
'bar': 2
}
Yes:
var options = {
'charting.legend.placement': 'none', // contains .
disabled: false
'default': undefined, // keyword
seed: undefined,
'type': 'text', // keyword
value: undefined,
};
Comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes!
Comments should be complete sentences. If a comment is a phrase or sentence, its first word should be capitalized, unless it is an identifier that begins with a lower case letter (never alter the case of identifiers!).
If a comment is short, the period at the end can be omitted. Block comments generally consist of one or more paragraphs built out of complete sentences, and each sentence should end in a period.
-
A space should occur between the comment marker and first letter. Capitalize the first letter.
Yes: // Compensate for border No: //compensate for border -
Most comments apply to apply to some line, paragraph, method, or other code element that directly follows them. There should be no intervening blank line. Comments hug elements.
Example:
// Collect changes to be made var bulkTemplateSets = {}; var bulkTemplateUnsets = []; var bulkSelfSets = {}; var queueTemplateSet = function(propName, propTemplate) { bulkTemplateSets[propName] = propTemplate; }; var queueLiteralSet = function(propName, propValue) { if (!that._isPushEnabled(propName)) { // Blank out any preexisting template unless this // is a pushed property bulkTemplateUnsets.push(propName); } bulkSelfSets[propName] = propValue; }; _.each(attrs, function(propValue, propName) { if (propValue instanceof TokenSafeString) { // Interpret as template. queueTemplateSet(propName, propValue.value); } else if (propValue instanceof TokenEscapeString) { // Interpret as literal value. queueLiteralSet(propName, propValue.value); } else if (_.isString(propValue) && options.tokens) { // Interpret as template. queueTemplateSet(propName, propValue); } else { // Otherwise interpret as a literal value. queueLiteralSet(propName, propValue); } });The first comment in the above example applies to the entire paragraph. The other comments apply to individual lines.
-
The trailing period for short single-line comments is optional and often omitted.
// This is a short comment <code element> -
Any comment with multiple sentences should have trailing periods.
// This is a longer comment that requires multiple lines. // And perhaps multiple sentences. // // Or even multiple paragraphs. <code element>Or alternatively:
/* * This is a longer comment that requires multiple lines. * And perhaps multiple sentences. * * Or even multiple paragraphs. */ <code element> -
Comments should be indented to the same level as the element they describe.
Yes:
// Lorem ipsum sig dilor amit makeItSo();No:
// Lorem ipsum sig dilor amit makeItSo();
Some comments are designed to be easily identifiable by global searches and tools. These take the format:
// FLAGNAME: This is a short comment
<code element>
Or in longer form:
// FLAGNAME: This is a longer comment that requires multiple lines.
// And perhaps multiple sentences.
<code element>
Flag comments don't generally use the /* variety of long comments.
A TODO is a flag comment that indicates further action is needed on a set of code.
These comments should generally reference a JIRA that tracks the work identified by the TODO. That way the work isn't forgotten.
For example:
// TODO: Write test that checks whether get() is symmetric to set(). (DVPL-1610)
Code reviewers are encouraged to nag for the creation of JIRAs to track unmarked TODOs.
There are a few other flag comments that are occasionally used:
FIXME- Flags code that shouldn't be committed. Recognized by some people's local checkin guards.HACK- Warns maintainers of known brittleness.NOTE- Warns maintainers of other issues.XXX- Same asHACK. Not as clear. Less politically correct. Avoid.
In general:
-
Use JavaDoc style comments, as this is the syntax that has inspired the syntax of most documentation generator tools, and thus will likely to be supported by whatever tool is chosen in the future.
-
All public classes, methods, and other members of the public API should have a documentation comment.
-
Documentation comments are marked with
/**and*/. Notice the extra leading*that distinguishes doc comments from regular multi-line comments. -
File-level comments, such as a comment block at the top of a file, are not generally used. Class comments are typically used instead.
When documenting a class or method:
-
The leading sentence or paragraph should serve as the primary summary.
-
Additional paragraphs may be added to provide more detail. Notice that
<p>isn't used between different paragraphs here.
When documenting a class:
-
A class declaration should always assign to a new variable whose name matches the class name.
/** * A model with built-in data binding support. * * The set() and get() methods support a `tokens` boolean option. * When true, the set is interpreted as a template * that may contain token escapes such as "$indexName$". * * If a property is set to a template, it is defined as a computed property * based on the referenced tokens and kept up-to-date when those token * values change. */ var TokenAwareModel = BaseModel.extend({ });
When documenting a method:
-
The
@paramblock tag is used to describe method parameters. -
The
@returnblock tag (not shown here) is used to describe the return value. -
Dictionary-valued parameters used to pass keyword arguments may document the specific keywords as if it were a
dictParamName.keywordArgNameparameter./** * Creates a new token-aware model. * * @param attributes Initial attributes of this model. * @param options.tokenNamespace * Name of the namespace to use when resolving * unqualified token references such as $token$. * Defaults to 'default'. * @param options.retainUnmatchedTokens * If true, returns the computed value of * the specified property, but with unresolved * tokens retained in the output string. * For example the template '$first$ $last$' * would resolve to 'Bob $last$' if only * the $first$ token was defined * (and it was 'Bob'). * @param options.tokenEscaper * Escaping function that will be used to escape * all expanded token values. * @param options.* Interpreted the same way as in TokenAwareModel.set(). */ constructor: function(attributes, options) { ... },
Private API may be documented in a separate multi-line comment directly below the public doc comment.
If there are also implementation comments that apply to the same element, the implementation comments appear last.
/**
* Creates a new token-aware model.
*
* @param attributes Initial attributes of this model.
* ... ...
*/
/*
* Private API:
*
* @param options._tokenRegistry
* An alternate token registry to use other than
* `mvc.Components`. For use by tests only.
*/
// NOTE: Must override constructor() and not initialize()
// because this._templates and listeners need to be
// in place before the first (non-empty) call to set(),
// which the default constructor() does by default.
constructor: function(attributes, options) {
...
}
(Much of this is adapted from the JavaDoc style guide.)
-
OK to use phrases instead of complete sentences, in the interests of brevity.
This holds especially in the initial summary and in @param tag descriptions.
-
Use 3rd person (descriptive) not 2nd person (prescriptive).
Yes: Gets the label. No: Get the label. -
Method descriptions begin with a verb phrase.
Yes: Gets the label of this button. No: This method gets the label of this button. -
Class and field descriptions can omit the subject and simply state the object.
Yes: A button label. No: This field is a button label. -
Use "this" instead of "the" when referring to an object created from the current class.
Yes: Gets the toolkit for this component. No: Gets the toolkit for the component. -
Add description beyond the API name.
If the doc comment merely repeats the API name in sentence form, it is not providing more information. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the API name.
Any documentation that doesn't provide additional information should be omitted, particularly for @param and @return block tags.
Yes:
/** * Sets the tool tip text, which displays when the cursor * lingers over this component. */ setToolTipText: function(text) { ... },No:
/** * Sets the tool tip text. * * @param text The text of the tool tip. */ setToolTipText: function(text) { ... },
Block tags should be used in the following order:
- @param (methods and constructors only)
- @return (methods only)
- @deprecated
There are a few cases where a comment doesn't apply directly to an element:
In cases where an empty block would be unusual, a comment can be inserted to explain why the block is blank.
For example, in Java:
FileReader fileIn = new FileReader("input.txt", "UTF-8");
try {
...
} finally {
try {
fileIn.close();
} catch (IOException e) {
// ignore
}
}
switch (command) {
case 1:
...
// fallthrough
case 2:
...
break;
default:
break;
}
Sometimes it is useful to divide the methods in a large class into sections.
var MainWindow = function() {
this.initialize.apply(this, arguments);
};
_.extend(MainWindow, {
// === Init ===
initialize: function() {
...
},
_createContent: function() {
...
},
_createHeader: function() {
...
},
// === Events ===
_onButtonClick: function() {
...
},
_onDispose: function() {
...
}
});
Most JavaScript files we currently write aren't long enough to justify this kind of sectioning.
Commented out code should usually not be committed. Rather it should be deleted. It can always be restored later through version control if needed.
This guideline avoids leaving in code that becomes out of date, and leaving in temporary code that shouldn't be committed at all.
If you need to commit commented out code, it is recommended that there be no space between the comment marker and the related code. This gives it a distinct appearance from normal comments which use a single intervening space.
It is also recommended that an additional comment be provided that explains why the commented out code shouldn't be removed.
new TextInputView({
id: "rightField",
el: $("#rightField"),
// NOTE: If this default is specified, it will override the
// default defined in the view above.
//default: "$1.00 $2.00", // literal value
value: mvc.tokenSafe("$fullName$")
}).render();
In this example the commented out code is left in as an explanation for readers. Since this example comes from example code shipped with the Web Framework, there definitely will be future readers.
In general:
- Files:
myclass.js- All lower case.
- Packages:
splunkjs/mvc/myclass.js- Short. All lower case.
- Classes:
MyClass- Upper camel case.
- Methods, Fields, Variables:
myVar- Lower camel case.
- Constants:
MY_CONSTANT- Loud case.
Additionally:
-
A public class should be declared in a file whose name matches the class name, converted to all lowercase to match file naming conventions. So a class called
MyClassshould reside in file calledmyclass.js. -
Acronyms are considered words for the purposes of the above conventions. Including 2-letter acronyms.
Yes: HttpUrlConnection No: HTTPURLConnectionYes: getId No: getID -
Members that are not part of the public API should be named with a leading underscore. Especially when naming methods and fields.
When in doubt, a method should be considered private API and therefore named with a leading underscore.
A class's private methods should not be invoked externally unless there is comment in the class describing the exception. For example unit tests occasionally require access to private API, although this is discouraged when possible.
When a file consists of a single require-compatible class it should be defined with imports at the top, followed by the exported class, optional private classes, and top-level code at the end.
define(function(require, exports, module) {
var $ = require('jquery'); // (1) imports
var _ = require('underscore');
var Backbone = require('backbone');
var console = require('util/console');
var mvc = require('./mvc');
var Settings = require('./settings');
var BaseSplunkView = Backbone.View.extend({ // (2) top-level class
...
});
return BaseSplunkView; // (3) top-level code
});
-
Imports should be sorted alphabetically by the variable name, case-insensitive.
Thus symbolically-named imports like
$and_usually precede alphabetically-named imports. And$occurs before_when being pedantic.This makes it easy to see whether a prospective import has already been inserted. And alphabetical ordering is also easy to reformat with tools if needed.
-
Classes may be defined in many ways depending on what object-orientation library or manual approach is being used.
Here are a few examples if your environment is not opinionated:
Normal Class:
Underscore:
var _ = require('underscore'); var BaseSplunkView = function() { BaseSplunkView.prototype.initialize.apply(this, arguments); }; _.extend(BaseSplunkView.prototype, { initialize: function(...) { ... }, ... methods ... });Vanilla JS:
var BaseSplunkView = function() { BaseSplunkView.prototype.initialize.apply(this, arguments); }; BaseSplunkView.prototype.initialize = function(...) { ... }; ... methods ...Inheriting from a Normal Class:
Underscore:
var _ = require('underscore'); // NOTE: Cannot be detected as instanceof BaseSplunkView // using this implementation strategy. var DerivedSplunkView = function() { DerivedSplunkView.prototype.initialize.apply(this, arguments); }; _.extend(DerivedSplunkView.prototype, BaseSplunkView.prototype, { initialize: function(...) { BaseSplunkView.prototype.initialize.apply(this, arguments); ... constructor body ... }, ... methods ... });Vanilla JS:
Please don't implement inheritance manually. Use a library.
Inheriting from a Backbone Class:
var Backbone = require('backbone'); var DerivedSplunkView = Backbone.View.extend({ initialize: function(...) { ... }, ... methods ... });Many other class libraries have a similar syntax, perhaps varying the name of the constructor method.
Static Class:
var TokenUtils = { ... methods ... };
-
Only one var should be declared per var statement.
This makes new vars easier to recognize and insert.
Yes:
var ichi = 1; var ni = 2; var san = 3;No:
var ichi = 1, ni = 2, san = 3;No:
var ichi = 1, ni = 2, san = 3;Definitely not:
var ichi = 1; var ni = 2; var san = 3; -
Variables should have minimal (logical) scope. Therefore they should be declared as close to their first use as possible.
Thus variables used in a single paragraph should be declared in that paragraph. Variables used in multiple paragraphs should be declared in a (potentially separate) paragraph immediately preceding the first reading paragraph.
Yes:
var ship = dock.get('USS Enterprise'); ship.setRedAlert(true); var desiredEtaInSeconds = 15 * 60; // 15 min var distanceToTargetInLightSeconds = 1000; ship.setWarpFactor(distanceToTargetInLightSeconds / desiredEtaInSeconds); -
Trailing commas break IE. Don't use them.
Yes: var items = [ item1, item2 ]; No: var items = [ item1, item2, ];(If they didn't break IE, I'd recommend their use because it makes inserting new elements easier.)
-
Avoid using block statements (such as
iforwhile) without braces:Yes:
if (!this.data) { return; }No:
if (!this.data) return; -
Avoid having multiple statements on the same line.
Yes:
if (!this.data) { return; }No:
if (!this.data) { return; } -
Avoid monkeypatching classes or individual objects by altering prototypes. Especially not native classes. Use the Foreign Method pattern instead.
Monkeypatching introduces ordering dependencies, makes it difficult to determine where custom grafted functions came from, and can cause conflicts with other JavaScript libraries.
Yes:
var empty = function(self) { return (self.length === 0); } var a = []; if (empty(a)) { console.log('winning'); }No:
Array.prototype.empty = function() { return (this.length === 0); } var a = []; if (a.empty()) { console.log('losing'); } -
Return function values as early as possible to avoid deep nesting of if-statements.
And do not contort code to follow the old "single function, single return" guideline from C.
Yes:
var isPercentage = function(val) { if (val < 0) { return false; } if (val > 100) { return false; } return true; }No:
var isPercentage = function(val) { if (val < 0) { return false; } else { if (val > 100) { return false; } else { return true; } } }Definitely not:
var isPercentage = function(val) { var result; if (val < 0) { result = false; } else { if (val > 100) { result = false; } else { result = true; } } return result; } -
Prefer
undefinedovervoid(0)or_.isUndefined(...). It is more straightforward.Preferred:
if (x === undefined) { ... }Avoid:
if (_.isUndefined(x)) { ... }Definitely not:
if (x === void(0)) { ... } -
Do not use
eval.