Code Guidelines
---------------
A few code guidelines to try to stick to, please comment if none of these make
sense, they are pretty basic and mostly apply to old code.  However for people
who are looking at current code, they make take up bad habits that exist in the
current codebase.

Tabs
----

The current code uses tabs, not spaces.  Keep whitespace usage consistent
between files.  New files should use tabs.

Line-Wrapping
-------------

Lines should typically not be longer than 80 characters; if they are an attempt
should be made to wrap them.  Move code to the line below and indent once (\t).

errors.append(MalformedMetadata(
	errors.DESCRIPTION_TOO_LONG_ERROR % \
	(length, max_desc_len),
	attr='DESCRIPTION.toolong')

Do not do this:

errors.append(MalformedMetadata(
              errors.DESCRIPTION_TOO_LONG_ERROR % \
              (length, max_desc_len),
              attr='DESCRIPTION.toolong')

The mixing of tabs and spaces means other developers can't read what you did.
This is why the python peps state spaces over tabs; because with spaces the line
wrapping is always clear (but you cannot convert spaces as easily as tabwidth).

String
-------
Try not to use the functions in the string module, they are deprecated.

string.join(<iterable>," ")

should be replaced with:

" ".join(<iterable>)

and:

string.split(string, delimeter)

should be replaced with:

"somestring".split(delimeter)

Nearly all other methods in string work on string objects and have similar calling
conventions.

Comparisons
-----------

if foo == None

should be replaced with:

if foo is not None:

Is not does a reference comparison (address1 = address2 basically) and 
the == forces a by value compare (with __eq__())

Dict Lookups
------------

Try not to use has_key, you can use

if foo in dict

instead of if dict.has_key(foo)

Also don't do stuff like:

if foo in dict and dict[foo]:

Generally you can do two things here, if you are messing with defaults..

dict.get(foo, some_default)

will try to retrieve foo from dict, if there is a KeyError, will insert foo
into dict with the value of some_default.  This method is preferred in cases where
you are messing with defaults:

try:
	dict[foo]
except KeyError:
	dict[foo] = default_value

The get call is nicer (compact) and faster (try,except are slow).

Exceptions
----------

Don't use the format raise Exception, "string"
It will be removed in py3k.

YES:
  raise KeyError("No key")

NO:
  raise KeyError, "No key"

Imports
-------

Import things one per line

YES:
  import os
  import time
  import sys

NO:
  import os,sys,time

When importing from a module, you may import more than 1 thing at a time.

YES:
  from portage.module import foo, bar, baz

Multiline imports are ok (for now :))

Try to group system and package imports separately.

YES:
  import os
  import sys
  import time

  from portage.locks import lockfile
  from portage.versions import vercmp

NO:
  import os
  import portage
  import portage.util
  import time
  import sys

Try not to import large numbers of things into the namespace of a module.
I realize this is done all over the place in current code but it really makes it
a pain to do code reflection when the namespace is cluttered with identifiers 
from other modules.

YES:

from portage import output

NO:

from portage.output import bold, create_color_func, darkgreen, \
  green, nocolor, red, turquoise, yellow

The YES example imports the 'output' module into the current namespace.
The negative here is having to use output.COLOR all over the place instead of
just COLOR.  However it means during introspection of the current namespace
'green','red', 'yellow', etc. will not show up.

The NO example just imports a set of functions from the output module.  It is
somewhat annoying because the import line needs to be modified when functions
are needed and often unused functions are left in the import line until someone
comes along with a linter to clean up (does not happen often).  The color is a
bit clearer as

  print red('blar')

is shorter than:

  print output.red('blar')

Rationale: python -c 'import portage; dir(portage)' (circa 02/2008)