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 <[email protected]>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
_______________________________________________ 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
