changeset 15:17fec6eb9114

Added a VIFF coding style document.
author Martin Geisler <mg@daimi.au.dk>
date Sun, 17 Feb 2008 12:30:42 +0100
parents f2705ee7c60d
children 4d5df8256249
files docs/coding-style.txt docs/layout.rst
diffstat 2 files changed, 60 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/coding-style.txt	Sun Feb 17 12:30:42 2008 +0100
@@ -0,0 +1,56 @@
+.. -*- coding: utf-8 -*-
+
+===================
+ VIFF Coding Style
+===================
+
+The VIFF code tries to follow the coding style laid out in :PEP:`8`,
+which you should read or at least skim over. You can check your code
+against by running the pep8.py_ checker.
+
+.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py
+
+
+The VIFF Coding Style in Short
+------------------------------
+
+A summary of the rules:
+
+* Use four spaces for indention, never tabs.
+
+* Use a single space around binary operators.
+
+* Name classes using ``CamelCase``.
+
+* Name variables, function, and methods using lowercase words like
+  ``foo_bar``.
+
+* Write docstrings for your functions and methods. Include test for
+  doctest_ if possible.
+
+  .. _doctest: http://docs.python.org/lib/module-doctest.html
+
+* Try to be consistent.
+
+These rules are there to make the source code more readable for both
+old and new people.
+
+The Twisted Coding Style
+------------------------
+
+VIFF uses Twisted_ and their code follows a slightly different coding
+style. Their style is closer to the style used in Java where functions
+and methods are named ``fooBar`` instead of ``foo_bar``.
+
+When writing code which is close to Twisted code, you might want to
+follow that style too. If you subclass a Twisted class to override
+some behavior, you might be forced to follow their style.
+
+If you have a choice, then you should only use the Twisted style if
+you expect people to call both your code and the Twisted code — if
+people will only call your code, then please follow the standard VIFF
+coding style.
+
+.. _Twisted: http://twistedmatrix.com/
+
+.. include:: layout.rst
--- a/docs/layout.rst	Sun Feb 17 12:28:15 2008 +0100
+++ b/docs/layout.rst	Sun Feb 17 12:30:42 2008 +0100
@@ -1,3 +1,7 @@
+
+.. header::
+   [ `VIFF Documentation <index.html>`__ ]
+   [ `Coding Style <coding-style.html>`__ ]
 
 .. footer::
    `Return to the VIFF homepage <../index.html>`__.