JavaScript Style Guide
Code Conventions
We use only the
TAB
character for indentation.We use
UpperCamelCase
for class names, andlowerCamelCase
for method and property names.Methods and properties that begin with an underscore (
_
) areprivate
.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 tothis
, 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 communicatednon-
@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 fileIf 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.