Skip to content

Rhaptos Software Development

Personal tools
You are here: Home » Documentation » Developer Documentation » CNX/Rhaptos Coding Standards
Log in


Forgot your password?
 

CNX/Rhaptos Coding Standards

Document Actions
Coding Standards for Python, Plone, HTML, XML and XSLT development

General


  • When editing existing code, follow the coding style of the file for
    • Variable names
    • Whitespace 

Python

Classes/Modules

  • Follow the Plone coding style which is based on the Python Style Guild.  If using any Zope 3 components, use the Zope 3 Coding Standards.
  • Each class or module file should have the following header
    • Replace any field inside < > with the proper value
"""
<File Name> - <Description>

Author: <Author Name>
(C) 2008 Rice University

This software is subject to the provisions of the GNU Lesser General
Public License Version 2.1 (LGPL).  See LICENSE.txt for details.
"""
  • All tabs should be replaced with 4 spaces
    • If a file has a mix of tabs and spaces, correct the file to use spaces
    • If a file is using all tabs, use tabs
    • If a your editor will replace tabs with spaces, set it to use 4 spaces per tab

Comments

  • Each Python class, function and method should include a Docstring comment
    • Documentation for the following should be included
      • All parameters
      • Any exceptions that could be thrown
      • Any return value
    • Example comment (from Normen Mueller's Rhaptos blog entry ):

"""This is the purpose of the function foo

param1:type This is the description of param1
param2:type This is the description of param2
return: This is the description of the return
value and type of foo

throws: This is the description of each possible
exception thrown by foo

remarks: This is where any other information
related to the current function is
placed, e.g. warning, hints, usage,
preconditions, invariants etc. """

Naming

  • Variable names should be clear and descriptive
  • Variable names should be in all lower case letters with words separated by underscores
    • Example: good_variable_format
  • Constants should be in all capital letters with words separated by underscores
    • Example: GOOD_CONSTANT_FORMAT

Templates

Plone/Zope Templates


<tal:comment tal:replace="nothing">
This template is used for foo.

</tal:comment>

Template Overrides

  • template overrides should be avoided
  • They should only be used to customize a Plone product or for a customization between Rhaptos and CNX
  • If a template override is used, the changes made should be documented in the template

Template Python Scripts

  • Python scripts for templates should include a docstring similar to Python classes

HTML

  • HTML files, includes .cpt and .pt files, should have HTML tags properly nested
  • If code is removed or modified in an existing file, nesting of tags should be corrected
  • All tabs should be replaced by 4 spaces

XML/XSLT

  • All tabs should be replaced by 2 spaces
    • If a file has a mix of tabs and spaces, correct the file to use spaces
    • If a file is using all tabs, use tabs
    • If a your editor will replace tabs with spaces, set it to use 2 spaces per tab

Unit Tests

  • Python classes and modules should have a PyUnit, ZopeUnit or PloneUnit test.
  • Unit tests should test the logical path through the code
  • As defects are found, tests should be included for these defects.
  • Existing unit tests should be updated as the code is modified

Created by ew2
Last modified 2008-07-02 15:38