.. highlight:: python

=================
Odoo Guidelines
=================

This page introduce the new Odoo Coding Guidelines. This guidelines
aims to improve the quality of the code (better readability of source,
...) but also to improve Odoo Apps ! Indeed, a proper code will ease
the maintenance and debugging, lower the complexity and promote the
reliability.

Module structure
================

Directories
------------
A module is organised in a few directory :

- *data/* : demo and data xml
- *models/* : models definition
- *controllers/* : contains controllers (http routes).
- *views/* : contains the views and templates
- *static/* : contains the web assets, separated into *css/, js/, img/, lib/, ...*

File naming
------------
For *views* declarations, split backend views from (frontend)
templates in 2 differents files.

For *models*, split the business logic by sets of models, in each sets
select a main model, this model gives its name to the set. If there is
only one set of module, its name is the same as the module name. For
each set named <main_model> the following files may be created:

- models/<main_model>.py
- models/<inherited_main_model.py
- views/<main_model>_templates.xml
- views/<main_model>_views.xml

For instance, *sale* module introduce ``sale_order`` and
``sale_order_line`` where ``sale_order`` is dominant. So the
<main_model> files will be named *models/sale_order.py* and
*views/sale_order_views.py*.


For *data*, split them by purpose : demo or data. The filename will be
the main_model name, suffixed by *_demo.xml* or *_data.xml*.

For *controller*, the only file should be named *main.py*.

For *static files*, the name pattern is *<module_name>.ext* (i.e. :
static/js/im_chat.js, static/css/im_chat.css, static/xml/im_chat.xml,
...). Don't link data (image, libraries) outside Odoo : don't use an
url to an image but copy it in our codebase instead.

The complete tree should looks like

.. code-block:: text

    addons/<my_module_name>/
    |-- __init__.py
    |-- __openerp__.py
    |-- controllers/
    |   |-- __init__.py
    |   `-- main.py
    |-- data/
    |   |-- <main_model>_data.xml
    |   `-- <inherited_main_model>_demo.xml
    |-- models/
    |   |-- __init__.py
    |   |-- <main_model>.py
    |   `-- <inherited_main_model>.py
    |-- security/
    |   |-- ir.model.access.csv
    |   `-- <main_model>_security.xml
    |-- static/
    |   |-- img/
    |   |   |-- my_little_kitten.png
    |   |   `-- troll.jpg
    |   |-- lib/
    |   |   `-- external_lib/
    |   `-- src/
    |       |-- js/
    |       |   `-- <my_module_name>.js
    |       |-- css/
    |       |   `-- <my_module_name>.css
    |       |-- less/
    |       |   `-- <my_module_name>.less
    |       `-- xml/
    |           `-- <my_module_name>.xml
    `-- views/
        |-- <main_model>_templates.xml
        |-- <main_model>_views.xml
        |-- <inherited_main_model>_templates.xml
        `-- <inherited_main_model>_views.xml


.. note:: Filename should only use only ``[a-z0-9_]``

.. warning:: Use correct file permissions : folder 755 and file 644.

XML files
=========

Format
------
When declaring a record in XML,

- Place ``id`` attribute before ``model``
- For field declaration, ``name`` attribute is first. Then place the
  *value* either in the ``field`` tag, either in the ``eval``
  attribute, and finally other attributes (widget, options, ...)
  ordered by importance.

- Try to group the record by model. In case of dependencies between
  action/menu/views, the convention may not be applicable.
- Use naming convention defined at the next point
- The tag *<data>* is only used to set not-updatable data with ``noupdate=1``

.. code-block:: xml

    <record id="view_id" model="ir.ui.view">
        <field name="name">view.name</field>
        <field name="model">object_name</field>
        <field name="priority" eval="16"/>
        <field name="arch" type="xml">
            <tree>
                <field name="my_field_1"/>
                <field name="my_field_2" string="My Label" widget="statusbar" statusbar_visible="draft,sent,progress,done" statusbar_colors='{"invoice_except":"red","waiting_date":"blue"}' />
            </tree>
        </field>
    </record>


Naming xml_id
-------------

Security, View and Action
~~~~~~~~~~~~~~~~~~~~~~~~~

Use the following pattern :

* For a menu : *<model_name>_menu*
* For a view : *<model_name>_view_<view_type>*, where *view_type* is kanban, form, tree, search, ...
* For an action : the main action respects *<model_name>_action*.
  Others are suffixed with *_<detail>*, where *detail* is a underscore
  lowercase string explaining a little bit the action (Should not be
  long). This is used only if multiple action are declared for the
  model.
* For a group : *<model_name>_group_<group_name>* where *group_name*
  is the name of the group, genrally 'user', 'manager', ...
* For a rule : *<model_name>_rule_<concerned_group>* where
  *concerned_group* is the short name of the concerned group ('user'
  for the 'model_name_group_user', 'public' for public user, 'company'
  for multi-company rules, ...).

.. code-block:: xml

    <!-- views and menus -->
    <record id="model_name_menu" model="ir.ui.menu">
        ...
    </record>

    <record id="model_name_view_form" model="ir.ui.view">
        ...
    </record>

    <record id="model_name_view_kanban" model="ir.ui.view">
        ...
    </record>

    <!-- actions -->
    <record id="model_name_action" model="ir.actions.act_window">
        ...
    </record>

    <record id="model_name_action_child_list" model="ir.actions.act_window">
        ...
    </record>

    <!-- security -->
    <record id="model_name_group_user" model="res.groups">
        ...
    </record>

    <record id="model_name_rule_public" model="ir.rule">
        ...
    </record>

    <record id="model_name_rule_company" model="ir.rule">
        ...
    </record>



.. note:: View name use dot notation ``my.model.view_type`` or ``my.model.view_type.inherit`` instead of *"This is the form view of My Model"*.


Inherited XML
~~~~~~~~~~~~~
The naming pattern of inherited view is *<base_view>_inherit_<current_module_name>*. A module can extend a view only one time, suffix the orginal name with *_inherit_<current_module_name>*, where *current_module_name* is the technical name of the module extending the view.


.. code-block:: xml

    <record id="inherited_model_view_form_inherit_my_module" model="ir.ui.view">
        ...
    </record>


Python
======

PEP8 options
------------

Using a linter can help to see syntax and semantic warning or error. Odoo Source Code try to respect Python standard, but some of them can be ignored.

- E501: line too long
- E301: expected 1 blank line, found 0
- E302: expected 2 blank lines, found 1
- E126: continuation line over-indented for hanging indent
- E123: closing bracket does not match indentation of opening bracket's line
- E127: continuation line over-indented for visual indent
- E128: continuation line under-indented for visual indent
- E265: block comment should start with '# '

Imports
-------
The imports are ordered as

#. Externals libs (One per line sorted and splitted in python stdlib)
#. Imports of ``openerp``
#. Imports from Odoo modules (rarely, and only if necessary)

Inside these 3 groups, the imported lines are alphabetically sorted.

.. code-block:: python

    # 1 : imports of python lib
    import base64
    import re
    import time
    # 2 :  imports of openerp
    import openerp
    from openerp import api, fields, models # alphabetically ordered
    from openerp.tools.safe_eval import safe_eval as eval
    from openerp.tools.translate import _
    # 3 :  imports from odoo modules
    from openerp.addons.website.models.website import slug
    from openerp.addons.web.controllers.main import login_redirect


Idioms
-------

- Prefer ``%`` over ``.format()``, prefer ``%(varname)`` instead of position (This is better for translation)
- Try to avoid generators and decorators
- Always favor *Readability* over *conciseness* or using the language features or idioms.
- Use list comprehension, dict comprehension, and basic manipulation using ``map``, ``filter``, ``sum``, ... They make the code easier to read.
- The same applies for recordset methods : use ``filtered``, ``mapped``, ``sorted``, ...
- Each python file should have ``# -*- coding: utf-8 -*-`` as first line
- Use the ``UserError`` defined in ``openerp.exceptions`` instead of overriding ``Warning``, or find a more appropriate exception in *exceptions.py*
- Document your code (docstring on methods, simple comments for the tricky part of the code)
- Use meaningful variable/class/method names



Symbols
-------

- Odoo Python Class : use camelcase for code in api v8, underscore lowercase notation for old api.

.. code-block:: python

    class AccountInvoice(models.Model):
        ...

    class account_invoice(osv.osv):
        ...

- Variable name :
    - use camelcase for model variable
    - use underscore lowercase notation for common variable.
    - since new API works with record or recordset instead of id list, don't suffix variable name with *_id* or *_ids* if they not contain id or list of id.

.. code-block:: python

    ResPartner = self.env['res.partner']
    partners = ResPartner.browse(ids)
    partner_id = partners[0].id

- ``One2Many`` and ``Many2Many`` fields should always have *_ids* as suffix (example: sale_order_line_ids)
- ``Many2One`` fields should have *_id* as suffix (example : partner_id, user_id, ...)
- Method conventions
    - Compute Field : the compute method pattern is *_compute_<field_name>*
    - Search method : the search method pattern is *_search_<field_name>*
    - Default method : the default method pattern is *_default_<field_name>*
    - Onchange method : the onchange method pattern is *_onchange_<field_name>*
    - Constraint method : the constraint method pattern is *_check_<constraint_name>*
    - Action method : an object action method is prefix with *action_*. Its decorator is ``@api.multi``, but since it use only one record, add ``self.ensure_one()`` at the beginning of the method.

- In a Model attribute order should be
    #. Private attributes (``_name``, ``_description``, ``_inherit``, ...)
    #. Default method and ``_default_get``
    #. Fields declarations
    #. Compute and search methods in the same order than field declaration
    #. Constrains methods (``@api.constrains``) and onchange methods (``@api.onchange``)
    #. CRUD methods (ORM overrides)
    #. Action methods
    #. And finally, other business methods.

.. code-block:: python

    class Event(models.Model):
        # Private attributes
        _name = 'event.event'
        _description = 'Event'

        # Default methods
        def _default_name(self):
            ...

        # Fields declaration
        name = fields.Char(string='Name', default=_default_name)
        seats_reserved = fields.Integer(oldname='register_current', string='Reserved Seats',
            store=True, readonly=True, compute='_compute_seats')
        seats_available = fields.Integer(oldname='register_avail', string='Available Seats',
            store=True, readonly=True, compute='_compute_seats')
        price = fields.Integer(string='Price')

        # compute and search fields, in the same order that fields declaration
        @api.multi
        @api.depends('seats_max', 'registration_ids.state', 'registration_ids.nb_register')
        def _compute_seats(self):
            ...

        # Constraints and onchanges
        @api.constrains('seats_max', 'seats_available')
        def _check_seats_limit(self):
            ...

        @api.onchange('date_begin')
        def _onchange_date_begin(self):
            ...

        # CRUD methods
        def create(self):
            ...

        # Action methods
        @api.multi
        def action_validate(self):
            self.ensure_one()
            ...

        # Business methods
        def mail_user_confirm(self):
            ...


Javascript and CSS
==================
**For javascript :**

- ``use strict;`` is recommended for all javascript files
- Use a linter (jshint, ...)
- Never add minified Javascript Libraries
- Use camelcase for class declaration

**For CSS :**

- Prefix all your class with *o_<module_name>* where *module_name* is the technical name of the module ('sale', 'im_chat', ...) or the main route reserved by the module (for website module mainly, i.e. : 'o_forum' for website_forum module). The only exception for this rule is the webclient : it simply use *o_* prefix.
- Avoid using id
- Use bootstrap native class
- Use underscore lowercase notation to name class

Git
===

Commit message
--------------

Prefix your commit with

- **[IMP]** for improvements
- **[FIX]** for bug fixes
- **[REF]** for refactoring
- **[ADD]** for adding new resources
- **[REM]** for removing of resources
- **[MERGE]** for merge commits (only for forward/back-port)
- **[CLA]** for signing the Odoo Individual Contributor License

Then, in the message itself, specify the part of the code impacted by your changes (module name, lib, transversal object, ...) and a description of the changes.

- Always put meaning full commit message: commit message should be
  self explanatory (long enough) including the name of the module that
  has been changed and the reason behind that change. Do not use
  single words like "bugfix" or "improvements".

- Avoid commits which simultaneously impacts lots of modules. Try to
  splits into different commits where impacted modules are different
  (It will be helpful when we are going to revert that module
  separately).

.. code-block:: text

    [FIX] website, website_mail: remove unused alert div, fixes look of input-group-btn
    Bootstrap's CSS depends on the input-group-btn
    element being the first/last child of its parent.
    This was not the case because of the invisible
    and useless alert.

    [IMP] fields: reduce memory footprint of list/set field attributes

    [REF] web: add module system to the web client
    This commit introduces a new module system for the javascript code.
    Instead of using global ...


.. note:: The long description try to explain the *why* not the
   *what*, the *what* can be seen in the diff

