This document describes the common naming conventions for the ERP5 project ('jp jp',) ERP5 Naming Conventions text/plain None jp en 9998-12-31 00:00:00 2005-04-13 13:53:17 2002-06-20 09:55:16 () 0 This document defines ERP5 naming conventions. User Interface Conventions Text shown by the UI is classified into titles and sentences. Basically, they should be British English by default. The text is translated by TranslationService. To reduce the cost of translations, you should not increase the variation of messages shown to the user. In principle, words are written as "Word" or "word" according to the context. However, if words are abbriviations, they are written as "WORD" as long as this is natural according to the usage among English-speaking people. Example:: - ID (an abbriviation of identifier) - FAX (an abbriviation of facsimile) - VAT (an abbriviation of value added tax) Titles Module Titles Modules show titles in the window decoration bar and in ListBoxes. They should be plural, separated by space, with no article, and capitalized. Example:: Accounting Transactions Purchase Packing Lists Document Titles Documents show titles in the window decoration bar. They should be singular, sperated by space, with no article, and capitalized. Example:: Accouting Transaction Purchase Packing List If a document has sub-documents, the title of a ListBox follows the same rule as module titles written above. Example:: Accounting Transaction Lines Purchase Packing List Lines Tab Titles Documents show tabs with titles. The first tab should be "View". But, if a document has multiple views for different tasks, they should be "Task View", exceptionally. Example:: Accounting View Invoice View The second last tab should be "Details", if a document has a detailed view. The last tab should be "History", if a document has a history. One more tab is shown only to Managers. It should be put after anything else, and entitled with "Metadata". Other tabs, if any, should be singular or plural according to the context, separated by space, with no article, and capitalized. If there is no good reason, sigular forms should be used. Example:: Discount Transactions Field Titles The titles of fields, in ERP5 Forms and generated by Scripts and Page Templates, should be singular or plural according to the context, separated by space, with no article, and capitalized. If there is no good reason, singular forms should be used. Example:: Transaction ID First Name Delivery Date State Invoice Number Sentences Sentences should be syntactically correct and natural as English. Every sentence should be terminated with a period, a colon, or a semi-colon, according to the context. Every sentence should be plain simple. If you are not sure whether a noun should be singular or plural, use plural. Good Example:: %d objects have been saved. Bad Example:: %d object(s) has/have been saved. The user does not care about whether "1 object has been saved." or "1 object have been saved." as long as the user must choose which is appropriate by her own eyes. It is more important to produce readable text. If a sentence contains an URL or a path, you should insert space between the URL or the path, so that the user can easily select it by a mouse. Good Example:: The document is saved in /path/to/the/file . Bad Example:: The document is saved in /path/to/the/file. Coding Conventions "Python coding conventions":http://www.python.org/doc/essays/styleguide.html is a good start for python coders. It defines precisely the multipole naming conventions from which we have to choose. A must read. Zope extends the python object model by adding - Zope Objects: objects which can be published and accessed through the OFS implement acquisition of attributes and, in certain cases, skinning - Zope Methods: it is possible to extend the behaviour of a Zope Object as defined in its class by calling special kinds of methods (DTML, Page Template, Python Script) stored in the OFS as Zope Objects Pseudo Constant A pseudo-constant is a global reusable value stored as an attribute (of a Class, of a module) which is considered as a constant. Example:: CONSTANT_NAME Attributes, Properties and IDs Attributes can be assigned to an object, to a class. Properties can be assigned to Zope object. Example:: base_price attribute_name Variables Variables can be defined within a python method or function, within a python script Zope object, within a page template Zope Object or within a DTML Method Zope Object. Example:: base_price attribute_name Class Classes are defined in python within products. Example:: Document MetaResource Resource ClassName Interface mixedCase that, is CapitalizedWords with initial lowercase Example:: content dublinCore rdf interfaceName Method Methods are defined for each class in python. Example:: Title BasePrice edit setPrice Exceptions for mixed start:: set get view edit delete print list add Exception if ZMI:: manage_doMethodName Page Template Pages templates are stored as IDs in the OFS (therefore small caps) but act as methods of objects (therefore CapitalizedWords) Example:: content_AddToCart content_edit interfaceName_MethodName Z SQL Method Z SQL Methods are stored as IDs in the OFS but act as methods In portal_catalog:: z_method_name In portal_skins:: PortalType_zMethodName ERP5 Form ERP5 Forms are stored as IDs in the OFS and they are associated to one or more portal types or classes as actions. Example:: AccountModule_viewAccountList Base_viewUIDialog ListBox ListBoxes use list methods, count methods and stat methods. Example:: AccountingTransactionModule_zGetAccountingTransactionList AccountingTransactionModule_countAccountingTransactionList AccountingTransactionModule_statAccountingTransactionList List methods have the form ModuleType_getPortalTypeList (Script) or ModuleType_zGetPortalTypeList (Z SQL Method). Count methods have the form ModuleType_countPortalTypeList (Script) or ModuleType_zCountPortalTypeList (Z SQL Method). Stat methods have the form ModuleType_statPortalTypeList (Script) or ModuleType_zStatPortalTypeList (Z SQL Method). ListBoxes use selection names. Example:: module_name_selection normal stx normal html