r25 - 16 Aug 2006 - 14:51:43 - PhilippeBossutYou are here: OSAF >  Projects Web  >  ChandlerHome > DeveloperDocumentation > ChandlerCodingStyleGuidelines

Chandler Coding Style Guidelines

These coding style guidelines apply to Python code, we don't yet have any style guidlines for C/C++ code.

We would like Chandler code to follow general python conventions wherever possible.

  • Short summary of python conventions
    • Use four spaces for indents, all spaces (no tabs)
    • Write docstrings for all public modules, classes, methods, functions.
    • Use a maximum line length 80 chars. For long blocks of text (docstring, comments) 72 chars is recommended.
    • Imports should usually be on separate lines, at top of file, after module docstring/comments and before module globals/constants.
    • Booleans should be done using the Python 2.3 boolean support (True and False)
    • error handling should be done using exception handling
    • the Python flag for debug mode is __debug__

  • OSAF specific guidelines:
    • Document your public or framework APIs with epydoc.
      • Quick tutorial on epydoc
      • Examples of epydoc docstrings ChandlerEpydocStyleGuide * NOTE: We are using epydoc comments to autogenerate our API documention.
    • Write unit tests and check them in.
    • Use super(Class, self).method rather than Class.method for invoking super. This is especially important when multiple inheritance is involved. For more information see UsingSuper.
    • Use logging instead of print.
      • We are using the python logging module.
      • Don't check in print statements if you use them temporarily to chase a bug.
    • For view classes with a related persistent model class, put both classes in the same file. The view class should be prefixed with a wx, e.g. wxViewerParcel and ViewerParcel.
    • Module docstring:
         """
         Description of the module.
         """
    • If you are writing code for OSAF, you'll also want to include these in module docstring:
      • @copyright: Copyright (c) 2005 Open Source Applications Foundation
        • For new files; for old files, add the curent year, for example 2003-2005
      • @license: http://osafoundation.org/Chandler_0.1_license_terms.htm
    • Multiple classes in one python module is fine. Import a module, not specific classes. Example:
             import mypackage.mymodule as mymodule
             foo = mymodule.MyClass1()
             bar = mymodule.MyClass2()

  • Naming conventions
    • Data Model, Content Model, etc.
      • Kind names: CapWords
      • Attribute names: mixedCase
    • Package/directory names
      • use short names, all lowercase letters
    • Module/file names, Class names, Exception names, and Function names should be:
      • CapWords
      • If a module primarily contains a class, it should have the same name as the class.
    • Attribute names, global and local variables should be:
      • mixedCase
      • _mixedCaseWithLeadingUnderscore (if protected)
      • __mixedCaseWithDoubleLeadingUnderscore (if private)
    • Constants should be:
      • UPPER_CASE_WITH_UNDERSCORES
    • Acronyms
      • The trailing letters in an acronym should have the same capitalization as the first letter:
        • urlString (for attribute names, global and local variables)
        • URLString (for module, class, exception, function, and method names)
    • Method names
      • Method names should follow the convention of the other code in that area. Code that is primarily intimate with wxPython code should follow wxPython conventions (CapWords). Code that is primarily intimate with other Python libraries should use the same conventions as for variables (defined above).

  • Strings : as of 0.7alpha3, Chandler is i18n/l10n (Internationalization/Localization) ready. You must follow those guidelines when defining strings that will be displayed in the UI:
    • Unicode strings only
    • Use the Chandler message factory
    • Use python dictionary mapping strings with replacement values
    • In general, follow all the i18n Busy Developers Guidelines

Final notes

  • Do the right thing. Doing the right thing is more important than following the letter of the guidelines.
  • If you're writing code that could conceivably be contributed to wxPython, wxWindows, Python, or any other project, try to follow the guidelines of that project.
  • Follow the conventions of the module you're adding to, unless its a good idea to clean up the whole module.

External resources

  • Python Style guides
    • Python's style guide, PEP 8: http://www.python.org/peps/pep-0008.html
    • Python's Docstring conventions, PEP 257: http://www.python.org/peps/pep-0257.html
    • wxPython's style guide: http://www.wxpython.org/codeguidelines.php

  • David Jeske's post on Python Coding Standards
    • These look really interesting, we at OSAF haven't fully digested them yet.

  • Other style related links
    • Import details, including opinions on style: http://www.effbot.org/guides/import-confusion.htm
    • Zope related (generally thoughtful)
      • http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/CodingStyle
      • http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/Zope3DeveloperInfo

Contributors

  • KatieCappsParlante - 15 Oct 2002, 20 Feb 2003
  • DuckySherwood - 15 Apr 2003
  • TedLeung - 03 Feb 2004


Discussion

At some point we'll figure out some convention for display text lookup strings -- e.g. one could have the string "COMMENTS" to look up "Comments" or "Commentaire", and "ADD_COMMENT" for multi-word lookup. It's important to have a different lookup string than the English string that is displayed, because sometimes the same word or phrase in English gets translated into different strings in other languages. E.g. the word "To" in English could mean destination (as in an email) or date range (as in [July 13] to [July 18]). So for putting the single word "To" in a translation lookup file we're likely to need both EMAIL_TO and DATE_RANGE_TO.

I'm not fixated on exactly what the convention is, although I'll point out that something visually differentiated helps code reviewers detect if the coder remembered to use lookup strings, and helps GUI users to see if the coder remembered to actually follow the lookup step. Also I've found it useful for the convention to have some kind of known substring so that translation lookup strings can easily be searched for -- e.g. LOC_COMMENT and LOC_EMAIL_TO would show up if we decided to use the prefix "LOC_".

Finally, John points out that typically these should not appear in code, but in data files, since most of our GUI is laid out in data files.

This section is merely some ideas around coding guidelines related to i18n; we'll come up with more fixed guidelines some day.

-- LisaDusseault - 08 Jul 2004


PageInfo
PageType DevDocPage
MaintainedBy none
PageStatus Work in progress -- this page is still being drafted?
Trash.CommentsWelcome2 Feel free to contribute comments?
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r25 < r24 < r23 < r22 < r21 | More topic actions
 
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.