Coding Guidelines

Dabo Coding Guidelines

• Class names generally begin with an upper-case letter, with one exception: Dabo base classes are prefixed with a lower-case d to indicate their status as base classes.
• Class attributes and methods begin with a lower-case letter. Underscores in the name are to be avoided; instead, use interCaps to make the name easy to understand.
• When writing text strings, use double quotes. If the string needs to span more than one line, use triple-double quotes. Example:

  self.Caption = "Click Me"
  self.longString = """This is a multi-line string
  It spans three lines.
  This is the last line."""
  

• Any literal text to be displayed to the user should be wrapped by the _() function. This is a standard name for the localization function that takes the string and runs it through a localizer. Localization is still primitive in Dabo as of March 2006, and all that happens with this function is that the original string is returned unchanged. But as we add localization, your strings will automatically be localized by using this technique. You will need to import the function in your code; the line you need is: from dabo.dLocalize import _. Examples:

Yes:

if dabo.ui.areYouSure(_("Do you want to save your changes to %s?") % fieldName):

No:

if dabo.ui.areYouSure(_("Do you want to save your changes to %s?" % fieldName)):

In the first example, the localization function received "Do you want to save your changes to %s". In the second, the localization function received "Do you want to save your changes to LastName??", where LastName was string-substituted. This won't work because it is a dynamic string (evaluated at runtime) and the localization function needs a static string to match against.

• Docstrings should be added to all public methods (methods that will be used by people developing with Dabo). Short docstrings go on a single line; longer docstrings have their trailing quotes on a line by themselves. Some examples follow.

def someSimpleMethod(self, val):
    """Computes a value and returns it."""
    return val * 17

def someComplexMethod(self, val):
    """This is a very complex method. In order for you to understand
    what it's doing, I need to explain a lot of the steps involved, so
    that's why this docstring is so long.
    """
    <lots of code follows...>

• Properties: Dabo makes extensive use of properties, for several reasons. First, they tend to be self-documenting. Second, they allow for more Pythonic coding than the use of getters and setters, while still providing the control over the accessing and changing of the underlying values that get/set methods offer. Properties begin with upper-case letters, and use interCaps to make them readable. In their most common form, a property declaration should look something like this:

  def _getSomeProperty(self):
    return self._someProperty
  def _setSomeProperty(self, val):
    self._someProperty = val
  SomeProperty = property(_getSomeProperty, _setSomeProperty, None,
          _("Document what this property represents  (type of value)"))