452 lines
16 KiB
ReStructuredText
452 lines
16 KiB
ReStructuredText
The OpenERP Web open-source project
|
|
===================================
|
|
|
|
Getting involved
|
|
----------------
|
|
|
|
Translations
|
|
++++++++++++
|
|
|
|
Bug reporting
|
|
+++++++++++++
|
|
|
|
Source code repository
|
|
++++++++++++++++++++++
|
|
|
|
Merge proposals
|
|
+++++++++++++++
|
|
|
|
Coding issues and coding conventions
|
|
++++++++++++++++++++++++++++++++++++
|
|
|
|
Javascript coding
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
These are a number of guidelines for javascript code. More than coding
|
|
conventions, these are warnings against potentially harmful or sub-par
|
|
constructs.
|
|
|
|
Ideally, you should be able to configure your editor or IDE to warn you against
|
|
these kinds of issues.
|
|
|
|
Use ``var`` for *all* declarations
|
|
**********************************
|
|
|
|
In javascript (as opposed to Python), assigning to a variable which does not
|
|
already exist and is not explicitly declared (via ``var``) will implicitly
|
|
create a global variable. This is bad for a number of reasons:
|
|
|
|
* It leaks information outside function scopes
|
|
* It keeps memory of previous run, with potentially buggy behaviors
|
|
* It may conflict with other functions with the same issue
|
|
* It makes code harder to statically check (via e.g. IDE inspectors)
|
|
|
|
.. note::
|
|
It is perfectly possible to use ``var`` in ``for`` loops:
|
|
|
|
.. code-block:: javascript
|
|
|
|
for (var i = 0; i < some_array.length; ++i) {
|
|
// code here
|
|
}
|
|
|
|
this is not an issue
|
|
|
|
All local *and global* variables should be declared via ``var``.
|
|
|
|
.. note:: generally speaking, you should not need globals in OpenERP Web: you
|
|
can just declare a variable local to your top-level function. This
|
|
way, if your widget/addon is instantiated several times on the same
|
|
page (because it's used in embedded mode) each instance will have its
|
|
own internal but global-to-its-objects data.
|
|
|
|
Do not leave trailing commas in object literals
|
|
***********************************************
|
|
|
|
While it is legal to leave trailing commas in Python dictionaries, e.g.
|
|
|
|
.. code-block:: python
|
|
|
|
foo = {
|
|
'a': 1,
|
|
'b': 2,
|
|
}
|
|
|
|
and it's valid in ECMAScript 5 and most browsers support it in Javascript, you
|
|
should *never* use trailing commas in Javascript object literals:
|
|
|
|
* Internet Explorer does *not* support trailing commas (at least until and
|
|
including Internet Explorer 8), and trailing comma will cause hard-to-debug
|
|
errors in it
|
|
|
|
* JSON does not accept trailing comma (it is a syntax error), and using them
|
|
in object literals puts you at risks of using them in literal JSON strings
|
|
as well (though there are few reasons to write JSON by hand)
|
|
|
|
*Never* use ``for … in`` to iterate on arrays
|
|
*********************************************
|
|
|
|
:ref:`Iterating over an object with for…in is a bit tricky already
|
|
<for-in-iteration>`, it is far more complex than in Python (where it Just
|
|
Works™) due to the interaction of various Javascript features, but to iterate
|
|
on arrays it becomes downright deadly and errorneous: ``for…in`` really
|
|
iterates over an *object*'s *properties*.
|
|
|
|
With an array, this has the following consequences:
|
|
|
|
* It does not necessarily iterate in numerical order, nor does it iterate in
|
|
any kind of set order. The order is implementation-dependent and may vary
|
|
from one run to the next depending on a number of reasons and implementation
|
|
details.
|
|
* If properties are added to an array, to ``Array.prototype`` or to
|
|
``Object.prototype`` (the latter two should not happen in well-behaved
|
|
javascript code, but you never know...) those properties *will* be iterated
|
|
over by ``for…in``. While ``Object.hasOwnProperty`` will guard against
|
|
iterating prototype properties, they will not guard against properties set
|
|
on the array instance itself (as memoizers for instance).
|
|
|
|
Note that this includes setting negative keys on arrays.
|
|
|
|
For this reason, ``for…in`` should **never** be used on array objects. Instead,
|
|
you should use either a normal ``for`` or (even better, unless you have
|
|
profiled the code and found a hotspot) one of Underscore's array iteration
|
|
methods (`_.each`_, `_.map`_, `_.filter`_, etc...).
|
|
|
|
Underscore is guaranteed to be bundled and available in OpenERP Web scopes.
|
|
|
|
.. _for-in-iteration:
|
|
|
|
Use ``hasOwnProperty`` when iterating on an object with ``for … in``
|
|
********************************************************************
|
|
|
|
``for…in`` is Javascript's built-in facility for iterating over and object's
|
|
properties.
|
|
|
|
`It is also fairly tricky to use`_: it iterates over *all* non-builtin
|
|
properties of your objects [#]_, which includes methods of an object's class.
|
|
|
|
As a result, when iterating over an object with ``for…in`` the first line of
|
|
the body *should* generally be a call to `Object.hasOwnProperty`_. This call
|
|
will check whether the property was set directly on the object or comes from
|
|
the object's class:
|
|
|
|
.. code-block:: javascript
|
|
|
|
for(var key in ob) {
|
|
if (!ob.hasOwnProperty(key)) {
|
|
// comes from ob's class
|
|
continue;
|
|
}
|
|
// do stuff with key
|
|
}
|
|
|
|
Since properties can be added directly to e.g. ``Object.prototype`` (even
|
|
though it's usually considered bad style), you should not assume you ever know
|
|
which properties ``for…in`` is going to iterate over.
|
|
|
|
An alternative is to use Underscore's iteration methods, which generally work
|
|
over objects as well as arrays:
|
|
|
|
Instead of
|
|
|
|
.. code-block:: javascript
|
|
|
|
for (var key in ob) {
|
|
if (!ob.hasOwnProperty(key)) { continue; }
|
|
var value = ob[key];
|
|
// Do stuff with key and value
|
|
}
|
|
|
|
you could write:
|
|
|
|
.. code-block:: javascript
|
|
|
|
_.each(ob, function (value, key) {
|
|
// do stuff with key and value
|
|
});
|
|
|
|
and not worry about the details of the iteration: underscore should do the
|
|
right thing for you on its own [#]_.
|
|
|
|
Writing documentation
|
|
+++++++++++++++++++++
|
|
|
|
The OpenERP Web project documentation uses Sphinx_ for the literate
|
|
documentation (this document for instance), the development guides
|
|
(for Python and Javascript alike) and the Python API documentation
|
|
(via autodoc_).
|
|
|
|
For the Javascript API, documentation should be written using the
|
|
`JsDoc Toolkit`_.
|
|
|
|
Guides and main documentation
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The meat and most important part of all documentation. Should be
|
|
written in plain English, using reStructuredText_ and taking advantage
|
|
of `Sphinx's extensions`_, especially `cross-references`_.
|
|
|
|
Python API Documentation
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
All public objects in Python code should have a docstring written in
|
|
RST, using Sphinx's `Python domain`_ [#]_:
|
|
|
|
* Functions and methods documentation should be in their own
|
|
docstring, using Sphinx's `info fields`_
|
|
|
|
For parameters types, built-in and stdlib types should be using the
|
|
combined syntax:
|
|
|
|
.. code-block:: restructuredtext
|
|
|
|
:param dict foo: what the purpose of foo is
|
|
|
|
unless a more extensive explanation needs to be given (e.g. the
|
|
specification that the input should be a list of 3-tuple needs to
|
|
use ``:type:`` even though all types involved are built-ins). Any
|
|
other type should be specified in full using the ``:type:`` field
|
|
|
|
.. code-block:: restructuredtext
|
|
|
|
:param foo: what the purpose of foo is
|
|
:type foo: some.addon.Class
|
|
|
|
Mentions of other methods (including within the same class), modules
|
|
or types in descriptions (of anything, including parameters) should
|
|
be cross-referenced.
|
|
|
|
* Classes should likewise be documented using their own docstring, and
|
|
should include the documentation of their construction (``__init__``
|
|
and ``__new__``), using the `info fields`_ as well.
|
|
|
|
* Attributes (class and instance) should be documented in their
|
|
class's docstring via the ``.. attribute::`` directive, following
|
|
the class's own documentation.
|
|
|
|
* The relation between modules and module-level attributes is similar:
|
|
modules should be documented in their own docstring, public module
|
|
attributes should be documented in the module's docstring using the
|
|
``.. data::`` directive.
|
|
|
|
Javascript API documentation
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Javascript API documentation uses JsDoc_, a javascript documentation
|
|
toolkit with a syntax similar to (and inspired by) JavaDoc's.
|
|
|
|
Due to limitations of JsDoc, the coding patterns in OpenERP Web and
|
|
the Sphinx integration, there are a few peculiarities to be aware of
|
|
when writing javascript API documentation:
|
|
|
|
* Namespaces and classes *must* be explicitly marked up even if they
|
|
are not documented, or JsDoc will not understand what they are and
|
|
will not generate documentation for their content.
|
|
|
|
As a result, the bare minimum for a namespace is:
|
|
|
|
.. code-block:: javascript
|
|
|
|
/** @namespace */
|
|
foo.bar.baz = {};
|
|
|
|
while for a class it is:
|
|
|
|
.. code-block:: javascript
|
|
|
|
/** @class */
|
|
foo.bar.baz.Qux = [...]
|
|
|
|
* Because the OpenERP Web project uses `John Resig's Class
|
|
implementation`_ instead of direct prototypal inheritance [#]_,
|
|
JsDoc fails to infer class scopes (and constructors or super
|
|
classes, for that matter) and has to be told explicitly.
|
|
|
|
See :ref:`js-class-doc` for the complete rundown.
|
|
|
|
* Much like the JavaDoc, JsDoc does not include a full markup
|
|
language. Instead, comments are simply marked up in HTML.
|
|
|
|
This has a number of inconvenients:
|
|
|
|
* Complex documentation comments become nigh-unreadable to read in
|
|
text editors (as opposed to IDEs, which may handle rendering
|
|
documentation comments on the fly)
|
|
|
|
* Though cross-references are supported by JsDoc (via ``@link`` and
|
|
``@see``), they only work within the JsDoc
|
|
|
|
* More general impossibility to integrate correctly with Sphinx, and
|
|
e.g. reference JavaScript objects from a tutorial, or have all the
|
|
documentation live at the same place.
|
|
|
|
As a result, JsDoc comments should be marked up using RST, not
|
|
HTML. They may use Sphinx's cross-references as well.
|
|
|
|
.. _js-class-doc:
|
|
|
|
Documenting a Class
|
|
*******************
|
|
|
|
The first task when documenting a class using JsDoc is to *mark* that
|
|
class, so JsDoc knows it can be used to instantiate objects (and, more
|
|
importantly as far as it's concerned, should be documented with
|
|
methods and attributes and stuff).
|
|
|
|
This is generally done through the ``@class`` tag, but this tag has a
|
|
significant limitation: it "believes" the constructor and the class
|
|
are one and the same [#]_. This will work for constructor-less
|
|
classes, but because OpenERP Web uses Resig's class the constructor is
|
|
not the class itself but its ``init()`` method.
|
|
|
|
Because this pattern is common in modern javascript code bases, JsDoc
|
|
supports it: it is possible to mark an arbitrary instance method as
|
|
the *class specification* by using the ``@constructs`` tag.
|
|
|
|
.. warning:: ``@constructs`` is a class specification in and of
|
|
itself, it *completely replaces* the class documentation.
|
|
|
|
Using both a class documentation (even without ``@class`` itself)
|
|
and a constructor documentation is an *error* in JsDoc and will
|
|
result in incorrect behavior and broken documentation.
|
|
|
|
The second issue is that Resig's class uses an object literal to
|
|
specify instance methods, and because JsDoc does not know anything
|
|
about Resig's class, it does not know about the role of the object
|
|
literal.
|
|
|
|
As with constructors, though, JsDoc provides a pluggable way to tell
|
|
it about methods: the ``@lends`` tag. It specifies that the object
|
|
literal "lends" its properties to the class being built.
|
|
|
|
``@lends`` must be specified right before the opening brace of the
|
|
object literal (between the opening paren of the ``#extend`` call and
|
|
the brace), and takes the full qualified name of the class being
|
|
created as a parameter, followed by the character ``#`` or by
|
|
``.prototype``. This latter part tells JsDoc these are instance
|
|
methods, not class (static) methods..
|
|
|
|
Finally, specifying a class's superclass is done through the
|
|
``@extends`` tag, which takes a fully qualified class name as a
|
|
parameter.
|
|
|
|
Here are a class without a constructor, and a class with one, so that
|
|
everything is clear (these are straight from the OpenERP Web source,
|
|
with the descriptions and irrelevant atttributes stripped):
|
|
|
|
.. code-block:: javascript
|
|
|
|
/**
|
|
* <Insert description here, not below>
|
|
*
|
|
* @class
|
|
* @extends openerp.base.search.Field
|
|
*/
|
|
openerp.base.search.CharField = openerp.base.search.Field.extend(
|
|
/** @lends openerp.base.search.CharField# */ {
|
|
// methods here
|
|
});
|
|
|
|
.. code-block:: javascript
|
|
|
|
openerp.base.search.Widget = openerp.base.Controller.extend(
|
|
/** @lends openerp.base.search.Widget# */{
|
|
/**
|
|
* <Insert description here, not below>
|
|
*
|
|
* @constructs
|
|
* @extends openerp.base.Controller
|
|
*
|
|
* @param view the ancestor view of this widget
|
|
*/
|
|
init: function (view) {
|
|
// construction of the instance
|
|
},
|
|
// bunch of other methods
|
|
});
|
|
|
|
OpenERP Web over time
|
|
---------------------
|
|
|
|
Release process
|
|
+++++++++++++++
|
|
|
|
OpenSUSE packaging: http://blog.lowkster.com/2011/04/packaging-python-packages-in-opensuse.html
|
|
|
|
Roadmap
|
|
+++++++
|
|
|
|
Release notes
|
|
+++++++++++++
|
|
|
|
.. [#] More precisely, it iterates over all *enumerable* properties. It just
|
|
happens that built-in properties (such as ``String.indexOf`` or
|
|
``Object.toString``) are set to non-enumerable.
|
|
|
|
The enumerability of a property can be checked using
|
|
`Object.propertyIsEnumeable`_.
|
|
|
|
Before ECMAScript 5, it was not possible for user-defined properties
|
|
to be non-enumerable in a portable manner. ECMAScript 5 introduced
|
|
`Object.defineProperty`_ which lets user code create non-enumerable
|
|
properties (and more, read-only properties for instance, or implicit
|
|
getters and setters). However, support for these is not fully complete
|
|
at this point, and they are not being used in OpenERP Web code anyway.
|
|
|
|
.. [#] While using underscore is generally the preferred method (simpler,
|
|
more reliable and easier to write than a *correct* ``for…in``
|
|
iteration), it is also probably slower (due to the overhead of
|
|
calling a bunch of functions).
|
|
|
|
As a result, if you profile some code and find out that an underscore
|
|
method adds unacceptable overhead in a tight loop, you may want to
|
|
replace it with a ``for…in`` (or a regular ``for`` statement for
|
|
arrays).
|
|
|
|
.. [#] Because Python is the default domain, the ``py:`` markup prefix
|
|
is optional and should be left out.
|
|
|
|
.. [#] Resig's Class still uses prototypes under the hood, it doesn't
|
|
reimplement its own object system although it does add several
|
|
helpers such as the ``_super()`` instance method.
|
|
|
|
.. [#] Which is the case in normal Javascript semantics. Likewise, the
|
|
``.prototype`` / ``#`` pattern we will see later on is due to
|
|
JsDoc defaulting to the only behavior it can rely on: "normal"
|
|
Javascript prototype-based type creation.
|
|
|
|
.. _reStructuredText:
|
|
http://docutils.sourceforge.net/rst.html
|
|
.. _Sphinx:
|
|
http://sphinx.pocoo.org/index.html
|
|
.. _Sphinx's extensions:
|
|
http://sphinx.pocoo.org/markup/index.html
|
|
.. _Python domain:
|
|
http://sphinx.pocoo.org/domains.html#the-python-domain
|
|
.. _info fields:
|
|
http://sphinx.pocoo.org/domains.html#info-field-lists
|
|
.. _autodoc:
|
|
http://sphinx.pocoo.org/ext/autodoc.html
|
|
?highlight=autodoc#sphinx.ext.autodoc
|
|
.. _cross-references:
|
|
http://sphinx.pocoo.org/markup/inline.html#xref-syntax
|
|
.. _JsDoc:
|
|
.. _JsDoc Toolkit:
|
|
http://code.google.com/p/jsdoc-toolkit/
|
|
.. _John Resig's Class implementation:
|
|
http://ejohn.org/blog/simple-javascript-inheritance/
|
|
.. _\_.each:
|
|
http://documentcloud.github.com/underscore/#each
|
|
.. _\_.map:
|
|
http://documentcloud.github.com/underscore/#map
|
|
.. _\_.filter:
|
|
http://documentcloud.github.com/underscore/#select
|
|
.. _It is also fairly tricky to use:
|
|
https://developer.mozilla.org/en/JavaScript/Reference/Statements/for...in#Description
|
|
.. _Object.propertyIsEnumeable:
|
|
https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/propertyIsEnumerable
|
|
.. _Object.defineProperty:
|
|
https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/defineProperty
|
|
.. _Object.hasOwnProperty:
|
|
https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/hasOwnProperty
|