1
0
mirror of https://github.com/Mikaela/Limnoria.git synced 2024-12-21 10:13:13 +01:00
Limnoria/docs/STYLE.rst
James Vega a8d2e35fb1 Initial pass at Sphinx documentation.
Rename all existing documentation files to *.rst.
Fix up some of the formatting to work better as reStructuredText.
Add Sphinx's output directories to gitignore.
Signed-off-by: James Vega <jamessan@users.sourceforge.net>
2010-08-24 18:24:52 -04:00

214 lines
8.6 KiB
ReStructuredText

================
Style Guidelines
================
**Note:** Code not following these style guidelines fastidiously is likely
(*very* likely) not to be accepted into the Supybot 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 ``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.
* Database filenames should generally begin with the name of the plugin and
the extension should be 'db'. plugins.DBHandler does this already.
* 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.
* All plugin files should include a docstring decsribing what the plugin does.
This docstring will be returned when the user is 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 include
an argument list as their first line, and after that a blank line followed
by a longer description of what the command does. The argument list is used
by the ``syntax`` command, and the longer description is used by the
``help`` command.
* 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 on when
floats need to be formatted, e.g., ``%.2f``.
* 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 statements in the code
(commented out) so they can later be re-enabled. Remember that once code is
buggy, it tends to have more bugs, and you'll probably need those print
statements again.
* While on the topic of logs, note that we do not use % (i.e., str.__mod__)
with logged strings; we simple pass the format parameters as additional
arguments. The reason is simple: the logging module supports it, and it's
cleaner (fewer tokens/glyphs) to read.
* While still on the topic of logs, it's also important to pick the
appropriate log level for given information.
* DEBUG: Appropriate to tell a programmer *how* we're doing something
(i.e., debugging printfs, basically). If you're trying to figure out why
your code doesn't work, DEBUG is the new printf -- use that, and leave the
statements in your code.
* INFO: Appropriate to tell a user *what* we're doing, when what we're
doing isn't important for the user to pay attention to. A user who likes
to keep up with things should enjoy watching our logging at the INFO
level; it shouldn't be too low-level, but it should give enough
information that it keeps him relatively interested at peak times.
* WARNING: Appropriate to tell a user when we're doing something that he
really ought to pay attention to. Users should see WARNING and think,
"Hmm, should I tell the Supybot developers about this?" Later, he should
decide not to, but it should give the user a moment to pause and think
about what's actually happening with his bot.
* ERROR: Appropriate to tell a user when something has gone wrong.
Uncaught exceptions are ERRORs. Conditions that we absolutely want to
hear about should be errors. Things that should *scare* the user should
be errors.
* CRITICAL: Not really appropriate. I can think of no absolutely critical
issue yet encountered in Supybot; the only possible thing I can imagine is
to notify the user that the partition on which Supybot is running has
filled up. That would be a CRITICAL condition, but it would also be hard
to log :)
* 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 test there so
there's a place to add more tests later (and so we can 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 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.
* 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.
- db => a database handle.
- fd => a file-like object.
- msg => an ircmsgs.IrcMsg object.
- irc => an irclib.Irc object (or proxy)
- nick => a string that is an IRC nick.
- channel => a string that is an IRC channel.
- hostmask => a string that is a user's IRC prefix.
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.