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 _______________________________________________ Mailing list: https://launchpad.net/~openerp-expert-framework Post to : [email protected] Unsubscribe : https://launchpad.net/~openerp-expert-framework More help : https://help.launchpad.net/ListHelp
