From: Jeremy Stanley Date: Mon, 31 May 2010 02:59:38 +0000 (+0000) Subject: New coder guide document. X-Git-Tag: 0.0.1~306 X-Git-Url: https://mudpy.org/gitweb?a=commitdiff_plain;h=716d65bbefa1f3ad2bf85131b437bba52efa6385;p=mudpy.git 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 index 0000000..0e999dc --- /dev/null +++ b/doc/coder.txt @@ -0,0 +1,251 @@ +============= + coder guide +============= + +:Copyright: (c) 2004-2010 Jeremy Stanley . 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 +`_, 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 +`_ 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 +`_, 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 `_ 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 `_.