New coder guide document.

* doc/coder.txt: New document focused on topics of interest to
anyone wishing to modify the mudpy engine or get involved with the
project's development process.

diff --git a/doc/coder.txt b/doc/coder.txt
new file mode 100644 (file)
index 0000000..0e999dc
--- /dev/null
+++ b/doc/coder.txt
@@ -0,0 +1,251 @@
+=============
+ coder guide
+=============
+
+:Copyright: (c) 2004-2010 Jeremy Stanley <fungi@yuggoth.org>. Permission
+            to use, copy, modify, and distribute this software is
+            granted under terms provided in the LICENSE file distributed
+            with this software.
+
+This guide attempts to embody a rudimentary set of rules for developer
+submissions of source code and documentation targeted for inclusion
+within the mudpy project, as well as pointers to useful resources for
+those attempting to obtain a greater understanding of the software.
+
+.. sectnum:: :start: 1
+.. contents:: :local:
+
+--------
+ source
+--------
+
+As with any project, the mudpy source code could always be better
+documented, and contributions to that end are heartily welcomed. 
+
+version control system
+----------------------
+
+Git_ is used for version control on the project, and the archive can be
+cloned anonymously from http://mudpy.org/git/mudpy if desired. For now,
+detailed commits can be E-mailed to fungi@yuggoth.org, but there will
+most likely be a developer mailing list for more open presentation and
+discussion of patches soon.
+
+A Gitweb_ interface is available, to make the change history easier to
+browse. This is found at http://mudpy.org/gitweb/mudpy/ and should be
+fairly self-explanatory.
+
+A GNU-format_ ChangeLog file is generated automatically from repository
+commit logs, available at http://mudpy.org/res/src/mudpy/doc/ChangeLog
+and is included in the doc directory of all tarball/zip files, exported
+automatically after each new commit. The export script, `git2gch
+<http://mudpy.org/res/src/mudpy/bin/git2gch>`_, is included in the bin
+directory.
+
+.. _Git: http://git-scm.com/
+.. _Gitweb: http://git.wiki.kernel.org/index.php/Gitweb
+.. _GNU-format: http://www.gnu.org/prep/standards/html_node
+                /Style-of-Change-Logs.html#Style-of-Change-Logs
+
+application program interface
+-----------------------------
+
+API documentation is maintained within docstrings in the mudpy source
+code. Browsable API documentation (automatically generated with Epydoc_)
+is maintained at http://mudpy.org/res/epydoc/ and refreshed with each
+new commit.
+
+.. _Epydoc: http://epydoc.sourceforge.net/
+
+regression testing
+------------------
+
+All new commits are tested using the `test
+<http://mudpy.org/res/src/mudpy/bin/test>`_ regression testing script in
+the bin directory of the source archive, to help ensure the software is
+continually usable. Any new features should be accompanied by suitable
+regression tests so that their functionality can be maintained properly
+through future releases.
+
+-------
+ style
+-------
+
+This section is primarily a summary of Guido van Rossum and Barry
+Warsaw's `Style Guide for Python Code
+<http://www.python.org/dev/peps/pep-0008/>`_, and borrows heavily from
+it. Explanation of these rules and the reasoning behind them can be
+found therein. When in need of sample code or other examples, any common
+source code file or text document file distributed as part of mudpy
+should serve as a suitable reference.
+
+indentation
+-----------
+
+* Use 3 spaces per indentation level. (This is a deviation from Python
+  PEP-8, which encourages 4-space tab stops, and as such the project may
+  be reformatted to conform at some future date).
+
+tabs or spaces
+--------------
+
+* Spaces only--no tabs ever. (Exception: Special file formats like `GNU
+  ChangeLog <http://www.gnu.org/prep/standards/html_node/
+  Style-of-Change-Logs.html#Style-of-Change-Logs>`_ require tabs for
+  historical reasons.)
+
+maximum line length
+-------------------
+
+* Limit all lines to a maximum of 79 characters.
+
+* For flowing long blocks of text (docstrings, comments, documentation
+  files and text-based data files), limiting the length to 72 characters
+  is recommended.
+
+* The preferred way of wrapping long lines is by using Python's implied
+  line continuation inside parentheses, brackets and braces. Make sure
+  to indent the continued line appropriately.
+
+* The preferred place to break around a binary operator is *after* the
+  operator, not before it.
+
+* When bracketed code is expanded into multiple lines, its terminating
+  bracket is indented the same amount as the line on which its
+  corresponding initial bracket appears (essentially K&R style).
+
+* If bracketed parameters are too lengthy/numerous to fit together on
+  one line, all are split onto individual lines.
+
+blank lines
+-----------
+
+* Separate top-level function and class definitions with two blank
+  lines.
+
+* Method definitions inside a class are separated by a single blank
+  line.
+
+* Extra blank lines may be used (sparingly) to separate groups of
+  related functions.
+
+* Blank lines may be omitted between a bunch of related one-liners (e.g.
+  a set of dummy implementations).
+
+* Use blank lines in functions, sparingly, to indicate logical sections.
+
+encodings
+---------
+
+* Always use ASCII whenever possible (decimal byte values 32 through 126
+  and line termination appropriate to the developer’s platform).
+
+* UTF-8 can be used, but only when a comment or docstring needs to
+  mention an author name that requires it; otherwise, using \\x,
+  \\u or \\U escapes is the preferred way to include non-ASCII
+  data in string literals.
+
+* Identifiers must be ASCII-only, and should use English words wherever
+  feasible.
+
+* In addition, string literals and comments must also be in ASCII. The
+  only exceptions are:
+
+  - test cases testing the non-ASCII features, and
+
+  - names of authors.
+
+* Any text constants in code are declared as Unicode; when actual byte
+  data is required instead, its entry point is documented clearly in
+  preparation for an eventual Python 3 transition.
+
+* All text handling routines operate on Unicode data, normalized as
+  early as possible to eliminate compositing sequences.
+
+imports
+-------
+
+* Any module required by code in a function or method is imported
+  immediately following the docstring; import x from y constructs are
+  avoided whenever possible. (This is a deviation from Python PEP-8,
+  which encourages imports at the beginning of each file, allows import
+  x from y, and requires absolute imports between modules in the same
+  package; as such the project may be reformatted to conform at some
+  future date).
+
+whitespace in expressions and statements
+----------------------------------------
+
+* Avoid extraneous whitespace
+
+  - immediately inside parentheses, brackets or braces;
+  
+  - immediately before a comma, semicolon, or colon;
+
+  - immediately before the open parenthesis that starts the argument
+    list of a function call;
+     
+  - immediately before the open parenthesis that starts an indexing or
+    slicing;
+     
+  - more than one space around an assignment (or other) operator to
+    align it with another.
+
+* Always surround arithmetic, assignment, boolean and comparison
+  operators with a single space on either side. (Exception: don't use
+  spaces around the = sign when used to indicate a keyword argument or a
+  default parameter value.)
+
+* Compound statements (multiple statements on the same line) are
+  generally discouraged.
+
+source comments
+---------------
+
+* Don't state what you're doing, but rather why you're doing it.
+
+* Always keep comments up-to-date when the code changes.
+
+* Comments should be complete English sentences.
+
+* If a comment is a phrase or sentence, its first word should be
+  capitalized, unless it is an identifier that begins with a lower case
+  letter (never alter the case of identifiers).
+
+* You should use only one space after a sentence-ending period.
+  
+* When writing English, Strunk and White apply.
+  
+* Block comments generally apply to some (or all) code that follows
+  them, and are indented to the same level as that code.
+  
+* Each line of a block comment starts with a # and a single space
+  (unless it is indented text inside the comment).
+
+* Paragraphs inside a block comment are separated by a line containing a
+  single #.
+  
+* About in-line comments (comments on the same line as a statement):
+
+  - Use them sparingly.
+  
+  - Separate them from the statement by at least two spaces.
+    
+  - Start them with a # and a single space.
+  
+documentation strings
+---------------------
+
+* Write docstrings for all public modules, functions, classes, and
+  methods.
+
+* The """ that ends a multi-line docstring should be on a line by
+  itself, and preceded by a blank line.
+
+* For one liner docstrings, it's okay to keep the closing """ on the
+  same line.
+
+* When markup is used in embedded documentation (docstrings, comment
+  blocks, et cetera) it conforms to the `reStructuredText Markup
+  Specification <http://
+  docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_.