5 :Copyright: (c) 2004-2010 Jeremy Stanley <fungi@yuggoth.org>. Permission
6 to use, copy, modify, and distribute this software is
7 granted under terms provided in the LICENSE file distributed
10 This guide attempts to embody a rudimentary set of rules for developer
11 submissions of source code and documentation targeted for inclusion
12 within the mudpy project, as well as pointers to useful resources for
13 those attempting to obtain a greater understanding of the software.
15 .. sectnum:: :start: 1
22 As with any project, the mudpy source code could always be better
23 documented, and contributions to that end are heartily welcomed.
25 version control system
26 ----------------------
28 Git_ is used for version control on the project, and the archive can be
29 cloned anonymously from http://mudpy.org/git/mudpy if desired. For now,
30 detailed commits can be E-mailed to fungi@yuggoth.org, but there will
31 most likely be a developer mailing list for more open presentation and
32 discussion of patches soon.
34 A Gitweb_ interface is available, to make the change history easier to
35 browse. This is found at http://mudpy.org/gitweb/mudpy/ and should be
36 fairly self-explanatory.
38 A GNU-format_ ChangeLog file is generated automatically from repository
39 commit logs, available at http://mudpy.org/res/src/mudpy/doc/ChangeLog
40 and is included in the doc directory of all tarball/zip files, exported
41 automatically after each new commit. The export script, `git2gch
42 <http://mudpy.org/res/src/mudpy/bin/git2gch>`_, is included in the bin
45 .. _Git: http://git-scm.com/
46 .. _Gitweb: http://git.wiki.kernel.org/index.php/Gitweb
47 .. _GNU-format: http://www.gnu.org/prep/standards/html_node
48 /Style-of-Change-Logs.html#Style-of-Change-Logs
50 application program interface
51 -----------------------------
53 API documentation is maintained within docstrings in the mudpy source
54 code. Browsable API documentation (automatically generated with Epydoc_)
55 is maintained at http://mudpy.org/res/epydoc/ and refreshed with each
58 .. _Epydoc: http://epydoc.sourceforge.net/
63 All new commits are tested using the `test
64 <http://mudpy.org/res/src/mudpy/bin/test>`_ regression testing script in
65 the bin directory of the source archive, to help ensure the software is
66 continually usable. Any new features should be accompanied by suitable
67 regression tests so that their functionality can be maintained properly
68 through future releases.
74 This section is primarily a summary of Guido van Rossum and Barry
75 Warsaw's `Style Guide for Python Code
76 <http://www.python.org/dev/peps/pep-0008/>`_, and borrows heavily from
77 it. Explanation of these rules and the reasoning behind them can be
78 found therein. When in need of sample code or other examples, any common
79 source code file or text document file distributed as part of mudpy
80 should serve as a suitable reference.
85 * Use 3 spaces per indentation level. (This is a deviation from Python
86 PEP-8, which encourages 4-space tab stops, and as such the project may
87 be reformatted to conform at some future date).
92 * Spaces only--no tabs ever. (Exception: Special file formats like `GNU
93 ChangeLog <http://www.gnu.org/prep/standards/html_node/
94 Style-of-Change-Logs.html#Style-of-Change-Logs>`_ require tabs for
100 * Limit all lines to a maximum of 79 characters.
102 * For flowing long blocks of text (docstrings, comments, documentation
103 files and text-based data files), limiting the length to 72 characters
106 * The preferred way of wrapping long lines is by using Python's implied
107 line continuation inside parentheses, brackets and braces. Make sure
108 to indent the continued line appropriately.
110 * The preferred place to break around a binary operator is *after* the
111 operator, not before it.
113 * When bracketed code is expanded into multiple lines, its terminating
114 bracket is indented the same amount as the line on which its
115 corresponding initial bracket appears (essentially K&R style).
117 * If bracketed parameters are too lengthy/numerous to fit together on
118 one line, all are split onto individual lines.
123 * Separate top-level function and class definitions with two blank
126 * Method definitions inside a class are separated by a single blank
129 * Extra blank lines may be used (sparingly) to separate groups of
132 * Blank lines may be omitted between a bunch of related one-liners (e.g.
133 a set of dummy implementations).
135 * Use blank lines in functions, sparingly, to indicate logical sections.
140 * Always use ASCII whenever possible (decimal byte values 32 through 126
141 and line termination appropriate to the developer’s platform).
143 * UTF-8 can be used, but only when a comment or docstring needs to
144 mention an author name that requires it; otherwise, using \\x,
145 \\u or \\U escapes is the preferred way to include non-ASCII
146 data in string literals.
148 * Identifiers must be ASCII-only, and should use English words wherever
151 * In addition, string literals and comments must also be in ASCII. The
154 - test cases testing the non-ASCII features, and
158 * Any text constants in code are declared as Unicode; when actual byte
159 data is required instead, its entry point is documented clearly in
160 preparation for an eventual Python 3 transition.
162 * All text handling routines operate on Unicode data, normalized as
163 early as possible to eliminate compositing sequences.
168 * Any module required by code in a function or method is imported
169 immediately following the docstring; import x from y constructs are
170 avoided whenever possible. (This is a deviation from Python PEP-8,
171 which encourages imports at the beginning of each file, allows import
172 x from y, and requires absolute imports between modules in the same
173 package; as such the project may be reformatted to conform at some
176 whitespace in expressions and statements
177 ----------------------------------------
179 * Avoid extraneous whitespace
181 - immediately inside parentheses, brackets or braces;
183 - immediately before a comma, semicolon, or colon;
185 - immediately before the open parenthesis that starts the argument
186 list of a function call;
188 - immediately before the open parenthesis that starts an indexing or
191 - more than one space around an assignment (or other) operator to
192 align it with another.
194 * Always surround arithmetic, assignment, boolean and comparison
195 operators with a single space on either side. (Exception: don't use
196 spaces around the = sign when used to indicate a keyword argument or a
197 default parameter value.)
199 * Compound statements (multiple statements on the same line) are
200 generally discouraged.
205 * Don't state what you're doing, but rather why you're doing it.
207 * Always keep comments up-to-date when the code changes.
209 * Comments should be complete English sentences.
211 * If a comment is a phrase or sentence, its first word should be
212 capitalized, unless it is an identifier that begins with a lower case
213 letter (never alter the case of identifiers).
215 * You should use only one space after a sentence-ending period.
217 * When writing English, Strunk and White apply.
219 * Block comments generally apply to some (or all) code that follows
220 them, and are indented to the same level as that code.
222 * Each line of a block comment starts with a # and a single space
223 (unless it is indented text inside the comment).
225 * Paragraphs inside a block comment are separated by a line containing a
228 * About in-line comments (comments on the same line as a statement):
230 - Use them sparingly.
232 - Separate them from the statement by at least two spaces.
234 - Start them with a # and a single space.
236 documentation strings
237 ---------------------
239 * Write docstrings for all public modules, functions, classes, and
242 * The """ that ends a multi-line docstring should be on a line by
243 itself, and preceded by a blank line.
245 * For one liner docstrings, it's okay to keep the closing """ on the
248 * When markup is used in embedded documentation (docstrings, comment
249 blocks, et cetera) it conforms to the `reStructuredText Markup
250 Specification <http://
251 docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_.