[pypy-svn] rev 2125 - pypy/trunk/doc/devel

[hpk at codespeak.net]

Author: hpk
Date: Thu Oct 30 18:43:15 2003
New Revision: 2125

Modified:
   pypy/trunk/doc/devel/coding-style.txt
Log:
revised/cleaned up the coding style document. 
please scrutinize it. 



Modified: pypy/trunk/doc/devel/coding-style.txt
==============================================================================
--- pypy/trunk/doc/devel/coding-style.txt	(original)
+++ pypy/trunk/doc/devel/coding-style.txt	Thu Oct 30 18:43:15 2003
@@ -3,104 +3,61 @@
 =====================================
 
 
-Directory Structure (example sketch)
-------------------------------------
-Here is an example of the directory structure::
-
- trunk/
-    src/
-        pypy/
-            interpreter/
-                pyframe.py
-                opcodes.py
-                opcodes_app.py
-                baseobjspace.py
-
-            module/     # mixed interpreter/app-code
-                builtin.py
-                builtin_app.py
-                struct.py
-                struct_app.py
-                test/
-                    test_struct_app.py
-                    test_struct.py
-
-            objspace/    # all objectsspaces go here
-                std/     # __init__.py pulls in the ObjSpace class
-                    floatobject.py
-                    intobject.py
-                    objspace.py
-                trivial.py
-
-            appspace/    # pure app-python modules converted/modified from CPython
-                parser.py
-                compiler/
-
-    www/
-        moincode/       -> site-packages/MoinMoin
-        moininstance/   -> wiki-instance
-            data/text/
-        issue/          -> issue-tracker-instance  # rename
-        htdocs-pypy/    -> www-root visible as /pypy/
-        util/           -> used for internal deployment (not visible to outside)
-    doc/                # meta-documents about pypy (unordered)
-
-end of example.
-
 Naming and environment
 -----------------------------
 
-- the PYTHONPATH should be set to the filesystem equivalent of
-  http://codespeak.net/svn/pypy/trunk/src
-  in fact the "autopath" module does this for you.
+- directories/modules/namespaces are always **lowercase**
 
-- ``__init__.py`` is always empty except for ``"pypy/objspace/*"``
+- classes are **CamelCase**
 
-- directories/modules/namespaces are always lowercase
+- never use plural names in directory and file names
 
-- classes are CamelCase
+- ``__init__.py`` is always empty except for ``"pypy/objspace/*"``
 
-- functions/methods  are lowercase and ``'_'-separated`` (if
+- functions/methods are lowercase and ``'_'-separated`` (if
   you need to separate at all)
 
+- not more than 4 directory nesting levels
+
+Committing
+----------
+
+- it's nice to write good log messages because several people
+  are reading the diffs. 
+
+- if you add (text/py) files to the repository then please run
+  pypy/tool/fixeol in that directory.  This will make sure 
+  that the property 'svn:eol-style' is set to native which 
+  allows checkin/checkout in native line-ending format.
+
 Object Spaces
 ---------------
 
 - objectspace classes are always spelled "ObjSpace"
     e.g. TrivialObjSpace
          StdObjSpace
+         FlowObjSpace
 
 - at interpreter level and in ObjSpace all boxed values
   have a leading ``w_`` to indicate "wrapped values".  This
   includes w_self.  Don't use ``w_`` in application level
   python only code.
 
-- not more than 4 directory nesting levels
-
-- never use plural names in directory and file names
-
-
 Test conventions
---------------------
-
-- each module has a canonical test-script (using the "unittests"
-  package if feasible)
+----------------
 
-    test/test_exactmodulename.py
-
-- each TestCase is named after the class it tests
-
-    class TestExactClass(unittest.TestCase):
-
-- all other testcases are assumed to test single/more functions
-  or something that spans more than one class
+- adding features usually requires adding appropriate tests. 
+  (It often even makes sense to first write the tests so that you are
+  sure that they actually can fail.) 
+
+- All over the pypy source code there are test/ directories 
+  which contain unittests.  Such scripts can usually be executed
+  directly or are collectively run by pypy/test_all.py 
 
 - every non-test file is forbidden to start with "t"
 
-- each test directory needs a copy of pypy/tool/autopath.py.
+- each test directory needs a copy of pypy/tool/autopath.py which
+  upon import will make sure that sys.path contains the directory
+  where 'pypy' is in. 
 
 - see some more information about tests at the test-design_ document. 
-
-------------------------------------------------------------------------------------------
-
-.. _test-design: ../devel/testdesign.html