openerp-expert-framework team mailing list archive

[Simone Orsi <simone.orsi@xxxxxxxxxxxx>]

Hi Sharoon,
I totally agree with you. We must have some policies on how to code modules.


Sharoon Thomas wrote:
> Hi All,
> 
> [Let me share my happiness of being part of this community and good luck
> to ourselves in this endeavour. ]
> 
> This mail as its subject states is to come up with a certain set of
> guidelines on coding in open ERP and new changes we should look forward
> to. The first step would be to organise the python code and a few
> extracts from PEP8/PEP20 in the context of open ERP
> 
> My humble suggestions are:
> 
> A. Strict PEP style guide compliance
> (http://www.python.org/dev/peps/pep-0008/)
>     * code is read much more often than it is written. - GVR. So we need
> to focus more on readability
>     1.> Indentation: Use Tab only (No Space) + Each tab should be 4
> spaces. (Some older editors have 8 spaces per tab. Note: editors=>vi/vim
> etc. not people :-P)
> 
>     2.> Blank Lines: Method definitions inside a class to be separated
> by a single blank line.
> 
>     3.> Code separation & Line length: Adviced line length less than 80
> (=79). In context of Open ERP split selection field, selection value
> tuplets into multiple lines. (This helps with version control too).
> 
>     4.> import statement. Imports must be on separate lines
>           - Imports are always put at the top of the file, just after
> any module comments and docstrings, and before module globals and
> constants.
> 
>       Imports should be grouped in the following order:
> 
>       1. standard library imports (time, datetime, os etc)
>       2. related third party imports (mako, relatario etc)
>       3. local application/library specific imports (osv, fields,
> external_osv etc)
>    5.> Comments that contradict the code are worse than no comments.
> Always make
>     a priority of keeping the comments up-to-date when the code changes!
> 
>     Comments should be complete sentences.  If a comment is a phrase or
>     sentence, its first word should be capitalized, unless it is an
> identifier
>     that begins with a lower case letter (never alter the case of
>     identifiers!).


I want to highlight this: COMMENT! COMMENT! COMMENT! :)
We should always comment our code.
I always lose a lot of time skimming methods for understanding what the
hell they do. A 3-lines comment can save a lot of time.


>     6.> - _single_leading_underscore: For on_change methods, methods of
> function fields, methods to populate selection fields and methods on
> view buttons. Also for methods which should not be called directly.
> (weak "internal use" indicator.  E.g. "from M import *" does not import
> objects whose name starts with an underscore.)
> 
>     - single_trailing_underscore_: used by convention to avoid conflicts
> with Python keyword, e.g.
>       Eg: Tkinter.Toplevel(master, class_='ClassName')
> 
>     - __double_leading_underscore: when naming a class attribute,
> invokes name
>       mangling (inside class FooBar, __boo becomes _FooBar__boo; see
> below).
> 
>     - __double_leading_and_trailing_underscore__: "magic" objects or
> attributes that live in user-controlled namespaces.
>       E.g.           __init__,  __import__ or __file__.  Never invent
> such names; only use them as documented.
> 
>      7.> - Open ERP module names: Modules should have short, all-
> lowercase names.  Underscores can be used in the module name if it
> improves readability.
> 
>      8.> Open ERP module versions : <<Can somebody who knows explain
> this>>
> 
>      9.> Exception Names : Because exceptions should be classes, the
> class naming convention applies here.  However, you should use the
> suffix "Error" on your exception names (if the exception actually is an
> error).
> Note: Open ERP has a lot of this: Line 880 in orm.py : raise _('The read
> method is not implemented on this object !') is wrong. This returns a
> string to method because _ in tools.translate return string. String
> exceptions are forbidden in py 2.6 and above. When raising an exception,
> use "raise osv_except(name,value,exception_type)" instead of the older
> form "raise ValueError, 'message'"
> 
>      10.> Function names should be lowercase, with words separated by
> underscores as necessary to improve readability.
> 
>      11.> Constants: Constants are usually declared on a module level
> and written in all capital letters with underscores separating words.
> Examples include MAX_OVERFLOW and TOTAL.
> 
>      12.> Designing for inheritance: Decide if class attributes must be
> public or not. If unsure make then non public by leading underscores. In
> Open ERP context only methods you might call by
> self.pool.get('xyz').method should have no trailing underscores Eg.
> method in function field can be non-public function _get_prod_price and
> this function may call a public function get_price
> 
>      13.> Code should be written in a way that does not disadvantage
> other implementations of Python. Eg. Avoid use of mx datetime (has been
> delaying oo_jython project for quite sometime)
> 
>      14.> Comparisons to singletons like None should always be done with
> 'is' or 'is not', never the equality operators. So if x==None is wrong,
> use x is None
> 
> Community: Please add/modify/suggest more conventions
> 
> Reference:
> Python Style Guide essay: GVR:
> http://wiki.laptop.org/go/Python_Style_Guide
> PEP8

I want to add another thing that might be useful: DOCUMENTATION!
But probably is better to talk about that on other thread.
This
https://lists.launchpad.net/openerp-expert-framework/msg00012.html
for example ;)


-- 
Simone Orsi              simone.orsi<at>domsense.com
Via Alliaudi, 19 - 10064  -  Pinerolo (TO)  -  Italy
Mobile: (+39) 3475004046  -   Fax: (+39) 01214469718
Domsense Srl                 http://www.domsense.com