bluemud python coding conventions guide

Created for bluemud by Brother Will and Brother Neil using various quotes from various places.

date who modifications
3/19/2001 brother will/brother neil first written
10/24/2001 brother will update to reflect doc-string changes et al
1/19/2002 brother will update to reflect new doc-string standards

this style guide

This guide is to be adhered to as much as possible so that we can read each other's code. There's no punishment except that people will be mad at you when they're trying to read your code and can't figure out what you're doing. They will tell you so via the standard methods of communication. If your code really sucks it might get rejected.

All problems with the style guide should be brought up with Brother Neil or Brother Will and they will adjudicate accordingly using semi-arbitrary methods involving no more energy than it would take to raise the temperature of four and a half moles of water 10 degrees with only a pen knife.

All style guide rules have been tested repeatedly on laboratory NPCs for safety precautionary measures--we're experts and we know what we're doing.



Indentation is by multiples of 2. Period. All spacing should be done with spaces--no tabs. Indent when you need to indent per Python syntax.

maximum line length

Maximum line length should be 80 characters--though you should seriously consider breaking up lines between 70 and 80 characters long to make things easier to deal with.

From Guido's Style guide:

The preferred way of wrapping long lines is by using Python's implied line continuation inside parentheses, brackets and braces. If necessary, you can add an extra pair of parentheses around an expression, but sometimes using a backslash looks better. Make sure to indent the continued line appropriately. ... Some examples (ed. adjusted by Will):

  class Rectangle(Blob):

    def __init__(self, 
      if width == 0 and height == 0 and \
             color == 'red' and emphasis == 'strong' or \
             highlight > 100:
        raise ValueError, "sorry, you lose"

      if width == 0 and height == 0 and (color == 'red' or
                                             emphasis is None):
        raise ValueError, "I don't think so"

      Blob.__init__(self, widt, height,
                        color, emphasis, highlight)


There are three mortal sins regarding comments:

  1. code with no comments
    Punishable by death--unless your code is so unbelievably good that it reads like English by itself. Even then it needs comments.
  2. comments that are poorly written
    Comments should be in English and should be either well-formed sentences or well-formed phrases. They should be informative--not redundant. They should be poetic--revel in your commenting.
  3. comments should not contradict the code
    This usually happens when you change the code but forget to change the comment. VERY BAD. Always keep the two up to date.

doc strings

All modules, classes, functions and methods should have doc strings. We run an ool generator against those doc strings and thus they become part of the online html documentation of your code. They help you-- they make it easier to look things up. Doc strings should be terse, informative, and beneficial. They should answer the "What is this?" and "How do I use it?" questions.

Doc strings are denoted by the use of """ around the docstring. Anything else is just a regular comment. Doc strings should be sentences--not phrases.

Doc strings for functions and methods should denote the types and descriptions of any arguments passed in and any return values.

Examples of doc strings:
  def getHitPoints(self):
    """Returns the number of hitpoints.


      (int) the current hitpoints

    return self._hitpoints

  def setHitPoints(self, newhitpoints):
    """Sets the number of hitpoints.

    Hps can never be negative (that would denote more than
    death.  As such, set_hitpoints will set the hitpoints to 0 if
    newhitpoints is not a positive number.


      'newhitpoints' -- (int) the new hp value

    if newhitpoints < 0:
      self._hitpoints = 0
      self._hitpoints = newhitpoints

  def setMaxHitPoints(self, maxhitpoints=None):
    """ Sets the maximum number of hitpoints.

    This is the maximum number of hitpoints that can never be
    exceeded except in the case of magical means or something
    along those lines.


      'maxhitpoints' -- (int or None) None if we should calculate
                        maxhitpoints based on level and constitution
                        or int if we should override this method

    if maxhitpoints == None:
      self._maxhitpoints = self._calculate_max()
      self._maxhitpoints = maxhitpoints

naming conventions

description of use naming scheme
package names lowercasewithnounderscores
module names lowercasewithnounderscores
global variables, module variables _first_letter_lower
public functions lower_case_with_underscores
private functions _lower_case_with_prefixed_underscore
class names UpperCaseFirstLetterOfWords
public methods firstLetterLower
private methods _firstLetterLower
class or instance level variables _firstLetterLower or _firstletterlower

Avoid abbreviations. Abbreviations that are condoned are in the following table:
thing abbreviated as...