<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title>[coding-style] </title> <meta content="text/html;charset=ISO-8859-1" name="Content-Type"/> <link href="style.css" media="screen" rel="stylesheet" type="text/css"/></head> <body> <div id="logo"><a href="http://codespeak.net"><img alt="py lib" height="114" id="pyimg" src="http://codespeak.net/img/pylib.png" width="154"/></a></div> <div id="metaspace"> <div class="project_title">[coding-style] </div> <div id="menubar"><a class="menu" href="index.html">index</a> <a class="menu" href="../../apigen/api/index.html">api</a> <a class="menu" href="../../apigen/source/index.html">source</a> <a class="menu" href="contact.html">contact</a> <a class="menu" href="download.html">download</a></div></div> <div id="contentspace"> <div id="docinfoline"> <div style="float: right; font-style: italic;"> </div></div> <div class="document" id="coding-style-for-the-py-lib-and-friendly-applications"> <h1 class="title">Coding Style for the Py lib and friendly applications</h1> <div class="contents topic"> <p class="topic-title first"><a id="contents" name="contents">Contents</a></p> <ul class="auto-toc simple"> <li><a class="reference" href="#honour-pep-8-style-guide-for-python-code" id="id1" name="id1">1 Honour PEP 8: Style Guide for Python Code</a></li> <li><a class="reference" href="#documentation-and-testing" id="id2" name="id2">2 Documentation and Testing</a></li> <li><a class="reference" href="#naming" id="id3" name="id3">3 naming</a></li> <li><a class="reference" href="#committing" id="id4" name="id4">4 committing</a></li> <li><a class="reference" href="#miscellaneous" id="id5" name="id5">5 Miscellaneous</a></li> </ul> </div> <div class="section"> <h1><a class="toc-backref" href="#id1" id="honour-pep-8-style-guide-for-python-code" name="honour-pep-8-style-guide-for-python-code">1 Honour PEP 8: Style Guide for Python Code</a></h1> <p>First of all, if you haven't already read it, read the <a class="reference" href="http://www.python.org/peps/pep-0008.html">PEP 8 Style Guide for Python Code</a> which, if in doubt, serves as the default coding-style for the py lib.</p> </div> <div class="section"> <h1><a class="toc-backref" href="#id2" id="documentation-and-testing" name="documentation-and-testing">2 Documentation and Testing</a></h1> <ul class="simple"> <li>generally we want to drive and interweave coding of documentation, tests and real code as much as possible. Without good documentation others may never know about your latest and greatest feature.</li> </ul> </div> <div class="section"> <h1><a class="toc-backref" href="#id3" id="naming" name="naming">3 naming</a></h1> <ul class="simple"> <li>directories, modules and namespaces are always <strong>lowercase</strong></li> <li>classes and especially Exceptions are most often <strong>CamelCase</strong></li> <li>types, i.e. very widely usable classes like the <tt class="docutils literal"><span class="pre">py.path</span></tt> family are all lower case.</li> <li>never use plural names in directory and file names</li> <li>functions/methods are lowercase and <tt class="docutils literal"><span class="pre">_</span></tt> - separated if you really need to separate at all</li> <li>it's appreciated if you manage to name files in a directory so that tab-completion on the shell level is as easy as possible.</li> </ul> </div> <div class="section"> <h1><a class="toc-backref" href="#id4" id="committing" name="committing">4 committing</a></h1> <ul class="simple"> <li>adding features requires adding appropriate tests.</li> <li>bug fixes should be encoded in a test before being fixed.</li> <li>write telling log messages because several people will read your diffs, and we plan to have a search facility over the py lib's subversion repository.</li> <li>if you add <tt class="docutils literal"><span class="pre">.txt</span></tt> or <tt class="docutils literal"><span class="pre">.py</span></tt> files to the repository then please make sure you have <tt class="docutils literal"><span class="pre">svn:eol-style</span></tt> set to native. which allows checkin/checkout in native line-ending format.</li> </ul> </div> <div class="section"> <h1><a class="toc-backref" href="#id5" id="miscellaneous" name="miscellaneous">5 Miscellaneous</a></h1> <ul class="simple"> <li>Tests are the insurance that your code will be maintained further and survives major releases.</li> <li>Try to put the tests close to the tested code, don't overload directories with names.</li> <li>If you think of exporting new py lib APIs, discuss it first on the <a class="reference" href="http://codespeak.net/mailman/listinfo/py-dev">py-dev mailing list</a> and possibly write a chapter in our <span class="incremental">future_</span> book. Communication is considered a key here to make sure that the py lib develops in a consistent way.</li> </ul> </div> </div> </div></body></html>