bluemud python coding conventions guide

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

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.

layout

indentation

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, 
                 width, 
                 height,
                 color='black', 
                 emphasis=None, 
                 highlight=0):
      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)

comments

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.

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

    returns:

      (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.

    arguments:

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

    """
    if newhitpoints < 0:
      self._hitpoints = 0
    else:
      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.

    arguments:

      '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()
    else:
      self._maxhitpoints = maxhitpoints

naming conventions