JavaScript Coding Guidelines

Overview of the guidelines for JavaScript coding for SAPUI5 with regard to code formatting, naming conventions, creating classes, and documentation.

For JavaScript, the following general guidelines apply:

Do not use global JavaScript variables; organize all global objects in an "sap.*" namespace structure, or extend the jQuery.sap object. The method jQuery.sap.declare(sModuleName) assists in doing so, see JavaScript Namespaces.

This also means: Do not use undeclared variables. When using global variables introduced by other libraries, declare the use in a special global comment: /*global JSZip, OpenAjax */.
Do not access internal (private) members of other objects.
Do not use console.log()
Use jQuery.sap.byId("<someId>") instead of jQuery("#<someId>") when <someId> is not a known string; certain characters in IDs need to be escaped for jQuery to work correctly.
Keep modifications of jQuery and other embedded Open Source to a minimum and document them clearly with the term SAP modification. Such modifications may not alter the standard behavior of the used library in a way that breaks other libraries

Code Formatting

For any code becoming part of SAPUI5, an ESLint check needs to run successfully, see Tools. The following list contains the most important formatting rules:

Add a semicolon after each statement, even if optional
No spaces before and after round braces (function calls, function parameters), but…
…use spaces after if/else/for/while/do/switch/try/catch/finally, around curly braces, around operators and after commas
Opening curly brace (functions, for, if-else, switch) is on the same line
Use "===" and "!==" instead of "==" and "!="; see the ESLint docu for special cases where "==" is allowed

The code should therefore look like this:

function outer(c, d) {
        var e = c * d;
        if (e === 0) {
            e++;
        }
        for (var i = 0; i < e; i++) {
            // do nothing
        }

        function inner(a, b) {
            return (e * a) + b;
        }

        return inner(0, 1);
    }

You can use the Eclipse default settings for the JavaScript editor, but make sure tabs are used for indentation.

Naming Conventions

We strongly recommend to use the Hungarian notation where name prefixes indicate the type for variables and object field names. But do not use the Hungarian notation for API method parameters: The documentation specifies the type in this case.

When using the Hungarian notation, use the prefixes highlighted below and continue with an uppercase letter (camelCase):

Sample	Type
sId	string
oDomRef	object
$DomRef	jQuery object
iCount	int
mParameters	map / assoc. array
aEntries	array
dToday	date
fDecimal	float
bEnabled	boolean
rPattern	RegExp
fnFunction	function
vVariant	variant types

Use CamelCase for class names, starting with an uppercase letter. HTML element IDs starting with sap-ui- are reserved for SAPUI5. DOM attribute names starting with data-sap-ui- as well as URL parameter names starting with sap- and sap-ui- are reserved for SAPUI5.

The following IDs are currently used:

ID	Description
`sap-ui-bootstrap`	ID of the bootstrap script tag
`sap-ui-library-*`	Prefix for UI libraries script tags
`sap-ui-theme-*`	Prefix for theme stylesheets link tags
`sap-ui-highlightrect`	ID of the highlight rect for controls in TestSuite
`sap-ui-blindlayer-*`	ID for `BlockLayer`
`sap-ui-static`	ID of the static popup area of UI5
`sap-ui-TraceWindowRoot`	ID of the `TraceWindowRoot`
`sap-ui-xmldata`	ID of the `XML Data Island`

Creating Classes

For the creation of classes, the following rules and guidelines apply:

Initialize and describe instance fields in the constructor function: this._bReady = false; // ready to handle requests
Define instance methods as members of the prototype of the constructor function: MyClass.prototype.doSomething = function(){...
Define static members (fields and functions) as members of the constructor function object itself: MyClass.doSomething = function(){...
Start the name of private members with an underscore: this._bFinalized
Combine constructor + methods + statics in a single JS source file named and located after the qualified name of the class; this is a precondition for class loading
Static classes do not have a constructor but an object literal; there is no pattern for inheritance of such classes. If inheritance is needed, use a normal class and create a singleton in the class.
Do not use SuperClass.extend(…) for subclasses. If no base class exists, the prototype is automatically initialized by JavaScript as an empty object literal and must not be assigned manually. Consider inheriting from sap.ui.base.Object
Subclasses call (or apply) the constructor of their base class: SuperClass.apply(this, arguments);

For more information, see Example for Defining a Class.

Documentation (JSDoc)

For documenting JavaScript, SAPUI5 uses the JSDoc3 toolkit which mimics JavaDoc. For an explanation of the available tags, see the JSDoc3 Toolkit Homepage.

Document the constructor with @class, @author, @since, and so on.
For subclasses, document the inheritance by using an @extends tag in their constructor doclet.
Document at least public and protected methods with JSDoc, mark them as @public/@protected.

When you also document private methods with JSDoc, mark them with @private. This is currently the default in SAPUI5, but not in JSDoc, so it is safer to explicitly specify it. "Protected" is not clearly defined in a JavaScript environment, in SAPUI5 it means: Not for use by applications, but might be used even outside the same class or subclasses, but only in closely related classes.
Document method parameters with type (in curly braces) and parameter name (in square brackets if optional).
Use @namespace for static helper classes that only provide static methods.

See the Example for creating a class in Example for Defining a Class.

Also see the list of common JSDoc pitfalls in Common Pitfalls in JSDoc.