============= 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 `_.