openerp-expert-framework team mailing list archive

[Sharoon Thomas <sharoonthomas@xxxxxxxxxxxx>]

Simone,

Can you create a public document where we can discuss and outline the
documentation style and what should be done by the module creator.

A sample here: Please add your suggestions about the coding guidelines here:

https://docs.google.com/Doc?docid=0ASrVtHC1t0UVZGRqbXQzMjhfMTVja2ZjODVkeg&hl=en

On Tue, Dec 8, 2009 at 1:35 PM, Simone Orsi <simone.orsi@xxxxxxxxxxxx>wrote:

> 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
>



-- 
Sharoon Thomas
Business Analyst & ERP Consultant
http://bit.ly/5FAJKU