Style.py :  » Web-Frameworks » Aquarium » aquarium-2.3 » aquarium » Python Open Source

Home
Python Open Source
1.3.1.2 Python
2.Ajax
3.Aspect Oriented
4.Blog
5.Build
6.Business Application
7.Chart Report
8.Content Management Systems
9.Cryptographic
10.Database
11.Development
12.Editor
13.Email
14.ERP
15.Game 2D 3D
16.GIS
17.GUI
18.IDE
19.Installer
20.IRC
21.Issue Tracker
22.Language Interface
23.Log
24.Math
25.Media Sound Audio
26.Mobile
27.Network
28.Parser
29.PDF
30.Project Management
31.RSS
32.Search
33.Security
34.Template Engines
35.Test
36.UML
37.USB Serial
38.Web Frameworks
39.Web Server
40.Web Services
41.Web Unit
42.Wiki
43.Windows
44.XML
Python Open Source » Web Frameworks » Aquarium 
Aquarium » aquarium 2.3 » aquarium » Style.py
'''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>

.. _Python-style guide: http://www.python.org/doc/essays/styleguide.html
.. _aquarium.screen.ScreenAPI: aquarium.screen.ScreenAPI-module.html

'''

__docformat__ = "restructuredtext"

# Created: Tue Mar 30 14:52:01 PST 2004
# Author: Shannon -jj Behrens
# Email: jjinux@users.sourceforge.net
#
# Copyright (c) Shannon -jj Behrens.  All rights reserved.
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.