doc/coder.txt

   1 =============
   2  coder guide
   3 =============
   4
   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
   8             with this software.
   9
  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.
  14
  15 .. sectnum:: :start: 1
  16 .. contents:: :local:
  17
  18 --------
  19  source
  20 --------
  21
  22 As with any project, the mudpy source code could always be better
  23 documented, and contributions to that end are heartily welcomed.
  24
  25 version control system
  26 ----------------------
  27
  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.
  33
  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.
  37
  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
  43 directory.
  44
  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
  49
  50 application program interface
  51 -----------------------------
  52
  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
  56 new commit.
  57
  58 .. _Epydoc: http://epydoc.sourceforge.net/
  59
  60 regression testing
  61 ------------------
  62
  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.
  69
  70 -------
  71  style
  72 -------
  73
  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.
  81
  82 indentation
  83 -----------
  84
  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).
  88
  89 tabs or spaces
  90 --------------
  91
  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
  95   historical reasons.)
  96
  97 maximum line length
  98 -------------------
  99
 100 * Limit all lines to a maximum of 79 characters.
 101
 102 * For flowing long blocks of text (docstrings, comments, documentation
 103   files and text-based data files), limiting the length to 72 characters
 104   is recommended.
 105
 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.
 109
 110 * The preferred place to break around a binary operator is *after* the
 111   operator, not before it.
 112
 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).
 116
 117 * If bracketed parameters are too lengthy/numerous to fit together on
 118   one line, all are split onto individual lines.
 119
 120 blank lines
 121 -----------
 122
 123 * Separate top-level function and class definitions with two blank
 124   lines.
 125
 126 * Method definitions inside a class are separated by a single blank
 127   line.
 128
 129 * Extra blank lines may be used (sparingly) to separate groups of
 130   related functions.
 131
 132 * Blank lines may be omitted between a bunch of related one-liners (e.g.
 133   a set of dummy implementations).
 134
 135 * Use blank lines in functions, sparingly, to indicate logical sections.
 136
 137 encodings
 138 ---------
 139
 140 * Always use ASCII whenever possible (decimal byte values 32 through 126
 141   and line termination appropriate to the developer’s platform).
 142
 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.
 147
 148 * Identifiers must be ASCII-only, and should use English words wherever
 149   feasible.
 150
 151 * In addition, string literals and comments must also be in ASCII. The
 152   only exceptions are:
 153
 154   - test cases testing the non-ASCII features, and
 155
 156   - names of authors.
 157
 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.
 161
 162 * All text handling routines operate on Unicode data, normalized as
 163   early as possible to eliminate compositing sequences.
 164
 165 imports
 166 -------
 167
 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
 174   future date).
 175
 176 whitespace in expressions and statements
 177 ----------------------------------------
 178
 179 * Avoid extraneous whitespace
 180
 181   - immediately inside parentheses, brackets or braces;
 182
 183   - immediately before a comma, semicolon, or colon;
 184
 185   - immediately before the open parenthesis that starts the argument
 186     list of a function call;
 187
 188   - immediately before the open parenthesis that starts an indexing or
 189     slicing;
 190
 191   - more than one space around an assignment (or other) operator to
 192     align it with another.
 193
 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.)
 198
 199 * Compound statements (multiple statements on the same line) are
 200   generally discouraged.
 201
 202 source comments
 203 ---------------
 204
 205 * Don't state what you're doing, but rather why you're doing it.
 206
 207 * Always keep comments up-to-date when the code changes.
 208
 209 * Comments should be complete English sentences.
 210
 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).
 214
 215 * You should use only one space after a sentence-ending period.
 216
 217 * When writing English, Strunk and White apply.
 218
 219 * Block comments generally apply to some (or all) code that follows
 220   them, and are indented to the same level as that code.
 221
 222 * Each line of a block comment starts with a # and a single space
 223   (unless it is indented text inside the comment).
 224
 225 * Paragraphs inside a block comment are separated by a line containing a
 226   single #.
 227
 228 * About in-line comments (comments on the same line as a statement):
 229
 230   - Use them sparingly.
 231
 232   - Separate them from the statement by at least two spaces.
 233
 234   - Start them with a # and a single space.
 235
 236 documentation strings
 237 ---------------------
 238
 239 * Write docstrings for all public modules, functions, classes, and
 240   methods.
 241
 242 * The """ that ends a multi-line docstring should be on a line by
 243   itself, and preceded by a blank line.
 244
 245 * For one liner docstrings, it's okay to keep the closing """ on the
 246   same line.
 247
 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>`_.