Created for bluemud by Brother Will and Brother Neil using various quotes from various places.
|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 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 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)
There are three mortal sins regarding comments:
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. 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
|description of use||naming scheme|
|global variables, module variables||_first_letter_lower|
|class or instance level variables||_firstLetterLower or _firstletterlower|