coder guide
=============
-:Copyright: (c) 2004-2010 Jeremy Stanley <fungi@yuggoth.org>. Permission
+:Copyright: (c) 2004-2014 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.
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.
+and is included in the doc directory of all tarball/zip files. The
+export script, git2gch, is included in the bin directory.
.. _Git: http://git-scm.com/
.. _Gitweb: http://git.wiki.kernel.org/index.php/Gitweb
-----------------------------
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/
+code.
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
+All new commits are tested using a 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
--------
+This project follows Guido van Rossum and Barry Warsaw's `Style Guide`_
+for Python Code (a.k.a. "PEP-8"). 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. Testing of all
+new patches with the flake8_ and pylint_ utilities is also highly
+recommended.
-* 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>`_.
+.. Style Guide: http://www.python.org/dev/peps/pep-0008/
+.. flake8: https://pypi.python.org/pypi/flake8
+.. pylint: https://pypi.python.org/pypi/pylint
projects / mudpy.git / commitdiff