Good coding practices

General Best Practices

Joel Burton's tutorial Best Practices for Plone Development is an essential starting point for anyone new to Plone development.  It covers the basics of working with filesystem code, source code management, configuration management, documentation, debugging and testing.  Some parts of it (e.g. configuration management) are getting a bit out of date, but overall, it's the single best starting point for the nitty-gritty of development technique.

In addition, Martin Aspeli's book Professional Plone Development provides a wealth of information on current best practices for Plone 3 development.  It covers all of Plone's current technologies and core development practices.

General coding standards

• Most of the logic in an add-on Product is written in Python. Following good Python coding style guidelines will help make your Product understandable and maintainable.
• Add-on products should be distributed as eggs. Further, Zope 3-style conventions discourage the use of the "magic" Products directory, although converting existing existing Zope 2-style Products to the packages using the Products.* namespace is encouraged.
  

• The Plone community values standards compliance and accessibility, so you should use proper XHTML, TALES, and CSS syntax. We recommend that you check your XHTML, CSS and RSS for compliance with the relevant W3C standards.   Strictly validating your templates for XHTML compliance is more important than ever before, since doing so will allow your products to work with the Chameleon template rendering engine, which provides 25-50% speed improvements over stock Plone 3/4.  It's not required yet, but it's very smart future-proofing, and just plain good coding practice.
  

• Avoid using DTML in your Plone add-on Product. Although Zope contains support for the DTML scripting language, DTML has been supplanted by TAL for building page templates and Python for underlying logic.

Think about Compatibility

Plone has traditionally supported the two most recent versions of Zope 2. This is generally a good model for add-ons to inherit: supporting the two most recent (major) versions of Plone; at the time of this writing that would be Plone 3 and Plone 4. It requires a little more work, but makes your contributions available to a much broader audience.

How I Learned To Stop Worrying and Love the API

One of the cool things about Plone is its API. Anything you can do through the web interface, you can do via filesystem code that manipulates the Plone API. Of course, that raises the question of how you discover what API methods to call. The following products can help.

DocFinderTab

DocFinderTab gives you instant, through-the-web access to the API for any object you can get to in the ZMI. In many ways, it's nicer than looking through the source code, since you see all the methods of the base classes, and nicer that looking in the debugger, because you get things arranged by base class. This product is dead simple to install and use. There's no excuse for not trying it out today. This really should get shipped as part of Zope.

Clouseau

Clouseau is an AJAX-based interactive Zope/Python prompt that lets you interact with Zope and Python directly from within Plone. It's very easy to use, has no dependencies, and is extremely handy.

Other products' Install.py files

A great way to see how to configure things is to see how other products do it, of course. Look at the Install.py for your favorite product. For example, to learn how to install new workflows from disk, see how we do this in PloneHelpCenter.

For a great introduction to using the Plone API, see:

• ifPeople's Plone API tutorial

Testing and DocTests

Plone has a strong culture of test-driven software development. In fact, many folks in the Plone community often judge the quality of add-on products by looking at the tests. Good tests mean that you can prove your product works, and helps you avoid breaking your product as you (and others) develop it on an ongoing basis.

Plone/Zope 3 developer Phillip von Weitershausen (PhiliKON) offers the following advice on testing:

• The top-level *.txt texts should be unit tests if you're writing a basic Zope 3-style component. Unit tests means you should be using DocTestSuite/DocFileSuite from zope.testing.doctest, not any of the convoluted ZopeTestCase test suites. If your test needs set-up, only load as much as you need. Avoid loading ZCML in a unit test.
• Tell a story into which you involve the reader using first person plural ("we"). Create the component, walk through its API, explain tough edge cases and why it's necessary to watch out for them (and to test them). I know, this takes time.
• If you're writing functional tests, talk to the application using the test browser (Products.Five.testbrowser.Browser, docs in zope.testbrowser/README.txt). It's a great way of testing interactive UIs in a doctest, and the result is very readable.

Phillip concludes:

Just because you write doctests doesn't mean you've also written docs. Testing and documenting is hard and doing them at the same time can mean you consolidate effort, but it also means you need think hard. Writing good tests, especially writing good doctests, is much more challenging than the coding itself. Be prepared to spend more time on this than the actual coding."

Lots more great information on testing can be found in Martin Aspeli's tutorial "Testing in Plone."

Also worth a read: Agile Documentation with doctest and epydoc

The following products can help you generate documentation for your add-on products.