Module aquarium.Style

Comment on style.

I am a huge proponent of the Python-style guide, mostly because it's reasonable, Guido wrote it, and I'd like all Python code to be consistent. Unfortunately, I am not in a position to suggest an HTML style guide since there is no obvious standard. (Nonetheless, I do heartily recommend DTD compliance.) Last of all, there is no official Cheetah style guide. Hence, I recommend the following:

• When a line contains HTML, placeholders, or directives that do not continue to the end of the line, indent the text using your choosen HTML style guide.

• When the line contains a single directive that continues to the end of the line, indent the text using the Python style guide.

• The above two statements suggest that the indentation of a line should depend on whether it's mostly HTML or Python. Python indentation has no affect on HTML indentation, and vice versa. This approach was inspired by Mason.

• The Python style guide has very specific recommendations for Python docs. However, the Cheetah equivalent of triple quoted strings will result in extraneous HTML whitespace when naively applied, which is occasionally a very bad thing. For the same reason, the body of a Cheetah method should start its indentation at the left column. Hence, I suggest the following:

  |#def __call__
  |#*doc-method: Single line.
  |
  |More text.
  |
  |*##slurp
  |<p>
  |  Hello, there!
  |</p>
  |#end def
  

• Likewise, if you use #implements foo, blank lines between methods will end up in the foo method. Hence, it's easier not to use #implements but to instead define an explicit foo method. This rule may be broken if HTML whitespace is irrelevent. For example, you may want to constrain Cheetah to just the top two lines of an otherwise HTML-only file.

• A screen should document the arguments that it expects. However, if it is expecting a bean (see aquarium.screen.ScreenAPI), the description of the bean itself should be left in the bean's class.

• When using gettext, do the following:

  |<ul>
  |  <li>$_("Indent one line strings inline.")</li>
  |  <li>
  |    $_("""\
  |Because indentation matters when doing a gettext lookup, don't indent
  |multi-line blocks of text.  Otherwise, if you need to change the
  |indentation, you'll have to update the translation catalog.""")
  |  </li>