flectra/addons/web/doc/guidelines.rst

Guidelines and Recommendations
==============================

Web Module Recommendations
--------------------------

Identifiers (``id`` attribute) should be avoided
''''''''''''''''''''''''''''''''''''''''''''''''

In generic applications and modules, ``@id`` limits the reusabily of
components and tends to make code more brittle.

Just about all the time, they can be replaced with nothing, with
classes or with keeping a reference to a DOM node or a jQuery element
around.

.. note::

    If it is *absolutely necessary* to have an ``@id`` (because a
    third-party library requires one and can't take a DOM element), it
    should be generated with `_.uniqueId
    <http://underscorejs.org/#uniqueId>`_ or some other similar
    method.

Avoid predictable/common CSS class names
''''''''''''''''''''''''''''''''''''''''

Class names such as "content" or "navigation" might match the desired
meaning/semantics, but it is likely an other developer will have the
same need, creating a naming conflict and unintended behavior. Generic
class names should be prefixed with e.g. the name of the component
they belong to (creating "informal" namespaces, much as in C or
Objective-C)

Global selectors should be avoided
''''''''''''''''''''''''''''''''''

Because a component may be used several times in a single page (an
example in OpenERP is dashboards), queries should be restricted to a
given component's scope. Unfiltered selections such as ``$(selector)``
or ``document.querySelectorAll(selector)`` will generally lead to
unintended or incorrect behavior.

OpenERP Web's :js:class:`~openerp.web.Widget` has an attribute
providing its DOM root :js:attr:`Widget.$el <openerp.web.Widget.$el>`,
and a shortcut to select nodes directly :js:attr:`Widget.$
<openerp.web.Widget.$>`.

More generally, never assume your components own or controls anything
beyond its own personal DOM.

Understand deferreds
''''''''''''''''''''

Deferreds, promises, futures, …

Known under many names, these objects are essential to and (in OpenERP
Web) widely used for making :doc:`asynchronous javascript operations
<async>` palatable and understandable.

OpenERP Web guidelines
----------------------

* HTML templating/rendering should use :doc:`qweb` unless absolutely
  trivial.

* All interactive components (components displaying information to the
  screen or intercepting DOM events) must inherit from
  :class:`~openerp.web.Widget` and correctly implement and use its API
  and lifecycle.

* All css classes must be prefixed with *oe_* .

* Asynchronous functions (functions which call :ref:`session.rpc
  <rpc_rpc>` directly or indirectly at the very least) *must* return
  deferreds, so that callers of overriders can correctly synchronize
  with them.

New Javascript guidelines
-------------------------

From v11, we introduce a new coding standard for Odoo Javascript code.  Here it
is:

* add "use strict"; on top of every odoo JS module

* name all entities exported by a JS module. So, instead of 

  .. code-block:: javascript

      return Widget.extend({
        ...
      });

you should use:

  .. code-block:: javascript

      var MyWidget = Widget.extend({
        ...
      });

      return MyWidget

* there should be one space between function and the left parenthesis:

  .. code-block:: javascript

    function (a, b) {}

* JS files should have a (soft) limit of 80 chars width, and a hard limit of 100

* document every functions and every files, with the style JSDoc.

* for function overriding other functions, consider adding the tag @override in
  the JS Doc.  Also, you can mention which method is overridden:

  .. code-block:: javascript

    /**
     * When a save operation has been confirmed from the model, this method is
     * called.
     *
     * @override method from field manager mixin
     * @param {string} id
     * @returns {Deferred}
     */
    _confirmSave: function (id) {

* there should be an empty line between the main function comments and the tags,
  or parameter descriptions

* avoid introspection: don't build dynamically a method name and call it.  It is
  more fragile and more difficult to refactor

* methods should be private if possible

* never read an attribute of an attribute on somethig that you have a reference.
  So, this is not good:

  .. code-block:: javascript

    this.myObject.propA.propB

* never use a reference to the parent widget

* avoid using the 'include' functionality: extending a class is fine and does
  not cause issue, including a class is much more fragile, and may not work.

* For the widgets, here is how the various attributes/functions should be
  ordered:

  1. all static attributes, such as template, events, custom_events, ...

  2. all methods from the lifecycle of a widget, in this order: init, willStart,
     start, destroy

  3. If there are public methods, a section titled "Public", with an empty line
    before and after

  4. all public methods, camelcased, in alphabetic order

  5. If there are private methods, a section titled "Private", with an empty line
    before and after

  6. all private methods, camelcased and prefixed with _, in alphabetic order

  7. If there are event handlers, a section titled "Handlers", with an empty line
    before and after

  8. all handlers, camelcased and prefixed with _on, in alphabetic order

  9. If there are static methods, they should be in a section titled "Static".
     All static methods are considered public, camelcased with no _.

* write unit tests

* for the event handlers defined by the key 'event' or 'custom_events', don't
  inline the function.  Always add a string name, and add the definition in the
  handler section

* one space after if and for

* never call private methods on another object

* object definition on more than one line: each element should have a trailing
  comma.

* strings: double quotes for all textual strings (such as "Hello"), and single
  quotes for all other strings, such as a css selector '.o_form_view'

* always use this._super.apply(this, arguments);

* keys in an object: ordered by alphabetic order