Capitalization
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.
Quoting
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."""
Localization
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.
Spaces vs. Tabs
One of the benefits of having your own project is that you get to settle religious issues such as this by decree. Therefore, Dabo code uses 1 tab per level of indentation. Continuation lines are indented 2 levels. Mixing spaces and tabs will result in a slow and painful death.
White Space
White space should visually group logical chunks of code. If a method is long enough to require blank lines, use a single blank line. There shall be two blank lines between regular methods, and three blank lines between top-level class definitions. For inline classes and methods, use your judgment.
Docstrings
Docstrings should be added to all public methods (methods that will be used by people developing with Dabo). If internal methods are non-trivial, there should be a docstring to explain what it does. 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. You must include a meaningful docstring that describes the property and indicates the value type. 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)"))
Properties are grouped at the end of a class definition, and are kept in alphabetical order to make them easy to find. Above the property definitions should be a block with the corresponding getter/setter methods, also arranged in alphabetical order for the property they are part of.
Parameters
When calling a method, parameters should have a space after a comma, but nowhere else. Examples:
Right:
def someMethod(self, foo, bar, baz, name=None, copy=None)
...
self.someMethod(foo, bar, baz, name="Something", copy=False)
Wrong:
def someMethod( self,foo,bar,baz,name = None,copy = None )
...
self.someMethod( foo,bar,baz,name = "Something",copy = False )