JavaScript Style Guide

Code Conventions

  • We use only the TAB character for indentation.
  • We use UpperCamelCase for class names, and lowerCamelCase for method and property names.
  • Methods and properties that begin with an underscore (_) are private.
  • Variables which contain jQuery elements should be named like $element, starting with a $. If it is a private jQuery element, prefix it with _$
  • We use that as a name for a closure reference to this, but try to avoid it if there’s the possibility of scope binding. Unfortunately jQuery’s event handlers do not allow easy scope binding.

Code Documentation

TODO: still determine this.

RequireJS module skeleton

All JavaScript files are RequireJS modules. They should follow this structure:

WARNING: still has to be done and discussed

<javascript> TODO </javascript>

Public API, Private methods and attributes

All methods and properties which are public API are marked with @api. The public API is supported for a longer period, and when a public API changes, this is clearly communicated in the Release Notes of a version.

On the contrary, we prefix private methods and attributes with an underscore. The user of an API should never override or call methods private methods as they are not meant for him to be overridden.

There’s also a type in between: methods which are not private but do not have a @api annotation. They can be safely overridden by the user, and he should not experience any unwanted behavior. Still, the names or functionality of these methods can change without notice between releases. In the long run, all of these methods should become part of the public API, as soon as they are proven in real life.

To sum it up, we have three types of methods/properties:

  • @api methods: Public API, the user of the object can rely on the functionality to be stable, changes in @api are clearly communicated
  • non-@api but also not private: The user can use it, but needs to be aware the method might still change.
  • private (prefixed with _): The user should never ever call or access this. Very strange things might happen.

Note

It is allowed to observe or bind to private properties within the Neos javascript code. This is because the property is not just meant as private object property, but as a non-api property.

When to use a new file

JavaScript files can become pretty large, so there should be a point to create a new file. Having just one class per file would be too much though, as this would end up in possibly hundreds of files, from which a lot will just have 20 lines of code.

As we use requirejs for loading dependencies we came up with the following guidelines for creating a new file:

  • Classes using a template include using the !text plugin should be in a separate file
  • If a class is extended by another class, then it should be in a separate file so it can be easily loaded as dependency
  • If a class is huge, and affecting readability of the definition file, then it should be moved to a single file
  • It has preference to keep classes grouped together, so classes with just a few lines stay grouped together, so if none of the above is true the classes stays in the main file.