[Wtfibs-commit] WTFibs STYLE,NONE,1.1

[James V. <jam...@us...>]

Update of /cvsroot/wtfibs/WTFibs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4680

Added Files:
	STYLE 
Log Message:
Initial import of STYLE doc.


--- NEW FILE: STYLE ---
====================================================================
Code not following these style guidelines fastidiously is likely
(*very* likely) not to be accepted into the WTFibs core.
====================================================================

Read PEP 8 (Guido's Style Guide) and know that we use almost all the
same style guidelines.

Maximum line length is 79 characters.  78 is a safer bet, though.
This is **NON-NEGOTIABLE**.  Your code will not be accepted while you
are violating this guidline.

Identation is 4 spaces per level.  No tabs.  This also is
**NON-NEGOTIABLE**.  Your code, again, will *never* be accepted while
you have literal tabs in it.

Single quotes are used for all string literals that aren't docstrings.
They're just easier to type.

Triple double quotes (""") are always used for docstrings.

Raw strings (r'' or r"") should be used for regular expressions.

Spaces go around all operators (except around '=' in default
arguments to functions) and after all commas (unless doing so keeps a
line within the 79 character limit).

Functions calls should look like this: "foo(bar(baz(x), y))".  They
should not look like "foo (bar (baz (x), y))", or like
"foo(bar(baz(x), y) )" or like anything else.  I hate extraneous
spaces.

Class names are StudlyCaps.  Method and function names are camelCaps
(StudlyCaps with an initial lowercase letter).  If variable and
attribute names can maintain readability without being camelCaps,
then they should be entirely in lowercase, otherwise they should also
use camelCaps.  Plugin names are StudlyCaps.

Imports should always happen at the top of the module, one import per
line (so if imports need to be added or removed later, it can be done
easily).

Unless absolutely required by some external force, imports should be
ordered by the string length of the module imported.  I just think it
looks prettier.

A blank line should be between all consecutive method declarations in
a class definition.  Two blank lines should be between all
consecutive class definitions in a file.  Comments are even better
than blank lines for separating classes.

Whenever creating a file descriptor or socket, keep a reference
around and be sure to close it.  There should be no code like this:
  s = urllib2.urlopen('url').read()
Instead, do this:
  fd = urllib2.urlopen('url')
  try:
    s = fd.read()
  finally:
    fd.close()
This is to be sure the bot doesn't leak file descriptors.

Whenever joining more than two strings, use string interpolation, not
addition:
  s = x + y + z # Bad.
  s = '%s%s%s' % (x, y, z) # Good.
  s = ''.join([x, y, z]) # Best, but not as general.
This has to do with efficiency; the intermediate string x+y is made
(and thus copied) before x+y+z is made, so it's less efficient.
People who use string concatenation in a for loop will be swiftly
kicked in the head.

When writing strings that have formatting characters in them, don't
use anything but %s unless you absolutely must.  In particular, %d
should never be used, it's less general than %s and serves no useful
purpose.  If you got the %d wrong, you'll get an exception that says,
"foo instance can't be converted to an integer." But if you use %s,
you'll get to see your nice little foo instance, if it doesn't
convert to a string cleanly, and if it does convert cleanly, you'll
get to see what you expect to see.  Basically, %d just sucks.

As a corrolary to the above, note that sometimes %f is used, but only
when floats need to be formatted, e.g., %.2f.

Common variable names:
  L => an arbitrary list.
  t => an arbitrary tuple.
  x => an arbitrary float.
  s => an arbitrary string.
  f => an arbitrary function.
  p => an arbitrary predicate.
  i,n => an arbitrary integer.
  cb => an arbitrary callback.
  fd => a file-like object.
When the semantic functionality (that is, the "meaning" of a variable
is obvious from context, one of these names should be used.  This
just makes it easier for people reading our code to know what a
variable represents without scouring the surrounding code.

Multiple variable assignments should always be surrounded with
parentheses -- i.e., if you're using the partition function, then
your assignment statement should look like
(good, bad) = partition(p, L).  The parentheses make it obvious that
you're doing a multiple assignment, and that's important because I
hate reading code and wondering where a variable came from.