Mikaela
/
Limnoria
mirror of https://github.com/Mikaela/Limnoria.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updated.

This commit is contained in:
Jeremy Fincher 2004-08-23 16:14:10 +00:00
parent 30c70820f0
commit ab35afa3a1
1 changed files with 59 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
docs/STYLE
View File

@ -2,23 +2,34 @@ Read PEP 8 (Guido's Style Guide) and know that we use almost all the
same style guidelines. same style guidelines.
Maximum line length is 79 characters. 78 is a safer bet, though. 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. 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. Single quotes are used for all string literals that aren't docstrings.
They're just easier to type. They're just easier to type.
Triple double quotes (""") are always used for docstrings. Triple double quotes (""") are always used for docstrings.
Spaces go around all operators (except around '=' in default arguments Raw strings (r'' or r"") should be used for regular expressions.
to functions) and after all commas (unless doing so keeps a line
within the 79 character limit). 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 Class names are StudlyCaps. Method and function names are camelCaps
(StudlyCaps with an initial lowercase letter). If variable and (StudlyCaps with an initial lowercase letter). If variable and
attribute names can maintain readability without being camelCaps, then attribute names can maintain readability without being camelCaps,
they should be entirely in lowercase, otherwise they should also use then they should be entirely in lowercase, otherwise they should also
camelCaps. Plugin names are StudlyCaps. use camelCaps. Plugin names are StudlyCaps.
Imports should always happen at the top of the module, one import per 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 line (so if imports need to be added or removed later, it can be done
@ -29,26 +40,30 @@ ordered by the string length of the module imported. I just think it
looks prettier. looks prettier.
A blank line should be between all consecutive method declarations in A blank line should be between all consecutive method declarations in
a class definition. Two blank lines should be between all consecutive a class definition. Two blank lines should be between all
class definitions in a file. Comments are even better than blank consecutive class definitions in a file. Comments are even better
lines for separating classes. than blank lines for separating classes.
Database filenames should generally begin with the name of the plugin Database filenames should generally begin with the name of the plugin
and the extension should be 'db'. baseplugin.DBHandler does this and the extension should be 'db'. plugins.DBHandler does this
already. already.
Whenever creating a file descriptor or socket, keep a reference around Whenever creating a file descriptor or socket, keep a reference
and be sure to close it. There should be no code like this: around and be sure to close it. There should be no code like this:
s = urllib2.urlopen('url').read() s = urllib2.urlopen('url').read()
Instead, do this: Instead, do this:
fd = urllib2.urlopen('url') fd = urllib2.urlopen('url')
s = fd.read() try:
fd.close() s = fd.read()
finally:
fd.close()
This is to be sure the bot doesn't leak file descriptors. This is to be sure the bot doesn't leak file descriptors.
All plugins should include a docstring decsribing what the plugin All plugin files should include a docstring decsribing what the
does. This docstring will be returned when the user wants help on a plugin does. This docstring will be returned when the user is
plugin. configuring the plugin. All plugin classes should also include a
docstring describing how to do things with the plugin; this docstring
will be returned when the user requests help on a plugin name.
Method docstrings in classes deriving from callbacks.Privmsg should Method docstrings in classes deriving from callbacks.Privmsg should
include an argument list as their first line, and after that a blank include an argument list as their first line, and after that a blank
@ -63,11 +78,20 @@ addition:
s = ''.join([x, y, z]) # Best, but not as general. s = ''.join([x, y, z]) # Best, but not as general.
This has to do with efficiency; the intermediate string x+y is made 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. (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 When writing strings that have formatting characters in them, don't
use anything but %s unless you absolutely must. In particular, %d 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 should never be used, it's less general than %s and serves no useful
purpose. 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 on
when floats need to be formatted, e.g., %.2f.
Use the log module to its fullest; when you need to print some values Use the log module to its fullest; when you need to print some values
to debug, use self.log.debug to do so, and leave those print to debug, use self.log.debug to do so, and leave those print
@ -77,18 +101,25 @@ bugs, and you'll probably need those print statements again.
While on the topic of logs, note that we do not use % with logged While on the topic of logs, note that we do not use % with logged
strings; we simple pass the format parameters as additional strings; we simple pass the format parameters as additional
arguemnts. arguments. The reason is simple: the logging module supports it, and
it's cleaner (fewer tokens/glyphs) to read.
SQL table names should be all-lowercase and include underscores to
separate words. This is because SQL itself is case-insensitive.
SQL statements in code should put SQL words in ALL CAPS:
SELECT quote FROM quotes ORDER BY random() LIMIT 1
All plugins should have test cases written for them. Even if it All plugins should have test cases written for them. Even if it
doesn't actually test anything but just exists, it's good to have the doesn't actually test anything but just exists, it's good to have the
test there so there's a place to add more tests later (and so we can test there so there's a place to add more tests later (and so we can
be sure that all plugins are adequately documented. be sure that all plugins are adequately documented; PluginTestCase
checks that every command has documentation)
All uses of eval() that expect to get integrated in Supybot must be All uses of eval() that expect to get integrated in Supybot must be
approved by jemfinch, no exceptions. approved by jemfinch, no exceptions. Chances are, it won't be
accepted. Have you looked at utils.safeEval?
SQL table names should be all-lowercase and include underscores to
separate words. This is because SQL itself is case-insensitive.
This doesn't change, however the fact that variable/member names
should be camel case.
SQL statements in code should put SQL words in ALL CAPS:
"""SELECT quote FROM quotes ORDER BY random() LIMIT 1""". This makes
SQL significantly easier to read.