mirror of https://github.com/Mikaela/Limnoria.git
updated.
This commit is contained in:
parent
30c70820f0
commit
ab35afa3a1
83
docs/STYLE
83
docs/STYLE
|
@ -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')
|
||||||
|
try:
|
||||||
s = fd.read()
|
s = fd.read()
|
||||||
|
finally:
|
||||||
fd.close()
|
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.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue