Coding Guidelines¶
Getting started¶
Before you can start making changes to Quod Libet you have to set up a development environment. See “Creating a Development Environment” for further details.
Source Overview¶
browsers/* | Things in the View menu |
ext/* | Extensions to QL / EF (i.e. the plugins) |
formats/* | File format support |
library/* | Library management code |
plugins/* | Base classes and structural enabling plugins |
operon/* | Operon, the QL CLI tool |
qltk/* | GTK+ widget subclasses/extensions |
util/* | General utility functions and setup code |
If you want to get a full overview of QL’s code, good places to start
are browsers/_base.py
, formats/_audio.py
, and library/libraries.py
.
Code Guidelines¶
We try to keep Quod Libet’s code in pretty good shape; when submitting a patch, it’s much easier to get it included quickly if you run through this checklist of common-sense code quality items. Make sure your patch:
- Passes existing tests. You can test this by executing
./setup.py test
- Is commented.
- Adds your name to the copyright header of every file you touch. This helps you get credit and helps us keep track of authorship.
General Guidelines¶
We prefer Python to C. We prefer ctypes
to compiled C wrappers. A good way
to get a new feature applied is if you include tests for it. Stock strings
and string reuse are awesome, but don’t make the interface awkward just to
avoid a new string.
Unit Tests¶
Quod Libet comes with a lot of tests, which helps us control regression.
To run them, run ./setup.py test
. Your
patch can’t break any unit tests, and if you change tests in a non-obvious
way (e.g. a patch that removes an entry point and also removes a test for
it is obvious) you should explain why.
It’s possible, indeed encouraged, that a changeset was for no other purpose than to improve the testing / test coverage, as there have been plenty of bugs that have slipped through. As usual, any fix associated with a confirmed bug should include tests that would have found the original bug, where possible.
Printing Text¶
All terminal output should go through the print_
, print_w
,
print_e
, or print_d
functions. These will handle Unicode recoding.
They also let us capture all output for debugging purposes.
Translations¶
All text that could be visible to users (with debugging mode disabled) should be marked translatable.
You can do this by simply using the _
function which is globally
available (through __builtin__):
print_w(_("This is translatable"))
To handle plural forms use ngettext
:
text = ngettext("%d second", "%d seconds", time) % time
It is good practice to add a comment for translators if the translation depends on the context:
# Translators: As in "by Artist Name"
text = _("by %s") % tag