1. Dwayne Litzenberger
  2. pyobjc


pyobjc / pyobjc / Doc / coding-style.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Coding style for PyObjC</title>
<meta name="Author" content="Ronald Oussoren" />
<meta name="Author" content="Bill Bumgarner" />
<meta name="Contact" content="pyobjc-dev@lists.sourceforge.net" />
<meta name="copyright" content="2002 The PyObjC Project" />
<h2>Coding style for PyObjC</h2>
<tbody valign="top">
<tr><th >Author:</th>
<td>Ronald Oussoren</td></tr>
<tr><th >Author:</th>
<td>Bill Bumgarner</td></tr>
<tr><th >Contact:</th>
<td><a href="mailto:pyobjc-dev@lists.sourceforge.net">pyobjc-dev@lists.sourceforge.net</a></td></tr>
<tr><th>URL:</th><td><a href="http://pyobjc.sourceforge.net/">http://pyobjc.sourceforge.net/</a><br />
<tr><th >Copyright:</th>
<td>2002 The PyObjC Project</td></tr>
<li><a href="#introduction" id="id1" name="id1">Introduction</a></li>
<li><a href="#python-code" id="id2" name="id2">Python code</a></li>
<li><a href="#c-code" id="id3" name="id3">C code</a></li>
<li><a href="#documentation" id="id4" name="id4">Documentation</a><ul>
<li><a href="#rest-in-docstrings" id="id5" name="id5">ReST in DocStrings</a></li>
<h2><a href="#id1" name="introduction">Introduction</a></h2>
<p>This document describes the coding style for PyObjC. Please use this style for
new code and try apply this style to existing code while working on it.</p>
<h2><a href="#id2" name="python-code">Python code</a></h2>
<p>The coding style for core Python is used (see <a href="http://www.python.org/peps/pep-0008.txt">PEP 8</a>). For consistency with
Cocoa we use mixed-case identifiers (like <code><span>lookUpClass</span></code>).</p>
<p>PyObjC extensions to Apple frameworks should be clearly marked as such, 
preferably by prefixing names with <code><span>PyObjC</span></code> or <code><span>pyobjc</span></code>. This should make it
clear to users where they should look for documentation of an item: The Apple
documentation or ours.</p>
<p>The entire <code><span>objc</span></code> module is an &quot;extension&quot; and all items exported from that
module should be documented in our documentation.</p>
<h2><a href="#id3" name="c-code">C code</a></h2>
<p>The coding style for core Python is used (see <a href="http://www.python.org/peps/pep-0007.txt">PEP 7</a>). We use <code><span>PyObjC</span></code> instead
of <code><span>Py</span></code> as the prefix for globally visible symbols.</p>
<h2><a href="#id4" name="documentation">Documentation</a></h2>
<p>All items exported by the objc module and all PyObjC extensions to Apple
frameworks (the AppKit and Foundation modules) should be documented using
<p>All documentation-- both standalone documents and docstrings-- should be
marked up using <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> [ReST].</p>
<h3><a href="#id5" name="rest-in-docstrings">ReST in DocStrings</a></h3>
<p><a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> can be used in doc strings.   ReST in DocStrings works
exactly like a standalone ReST document, but the ReST is broken up slightly
<p>To format the DocStrings to be ReST compatible, make the following
changes/additions to the source.  These examples were taken from source found
in the DocUtils source tree.</p>
<ol type="1">
<li>Add appropriate ReST style fields to the top of the document as comments:<pre>
# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 1.16 $
# Date: $Date: 2003/07/07 07:02:10 $
# Copyright: This module has been placed in the public domain.
<li>Add a module level variable that indicates that ReST is used to format
the text contained in the docstrings:<pre>
__docformat__ = 'reStructuredText'
<li>Format all other DocStrings as one normally would in Python.   Use ReST
style markup where appropriate.   For example, bulleted lists and
sections might commonly appear in the module or class docstrings.   The
docstrings for individual methods may use example blocks, hyperlinks, or
any other ReST markup.</li>