To make it easier to read patches and other contributions, the freevo source code should follow some basic guidelines. The latest release is far away from respecting the guidelines, but on SVN we are working on a cleaner code. Most of the guidelines are taking from the basic python guidelines.
- All files have a header. This header must include: a one line description, a longer description what this file does and how it interacts with others, and a name of a maintainer.
More code doc. Each class must have a doc string, explaining the purpose of the class. Some for functions, also describing the parameters and return values. No exceptions (not even eventhandler()). One exception: after a class description, __init__ only needs parameter description.
And even more doc: add comments inside the code what you are doing here. Some days ago I came across a 'if instance(self.parent, str)' and I wondered: how can this be? So more docs. Also document stuff like "now we build xy" and "add xy to z". And for 'if foo' in the line after the if "now we handle foo by doing bar".
Max line width is 120 chars, no more. It should be readable in a simple xterm. Indention is 4 spaces (use reindent.py to make clean files - run contrib/developer/reindent.py -h for more info). If you need a longer line, you should think of using a) a helper variable or b) move some code to an extra function.
- All variables/classes except tmp vars have clear names. Use file_dir, not fd or d.
- Config variables and constants are upper case, use an underline char to split words for better reading. So FOO, FOOBAR or FOO_BAR. Config variables also contain the code were they are used like AUDIO_MPLAYER_FOO is foo or audio, the mplayer plugin.
Other variables and functions are lowercase. To split words here also use _, not a capital letter. E.g.: foo, foobar, foo_bar, not Foo, fooBar.
Classes start with an uppercase char, followed by lowercase. To split words, use a capital letter, no _. E.g. Foo, Foobar or FooBar, not Foo_bar or Foo_Bar.
- Filenames are similar to variables/functions, no upper case letters.
- Some people like ( x , y ), others prefer (x, y), so do what you want here, both is ok.
- To make code readable, add an empty lines between blocks. Add two empty lines between functions.
- Do not use names of builtin functions (IMPORTANT!): dir, filter, str, file, etc
Strings: Use single-quotes in general (less visual clutter), double-quote if you want to use single-quotes inside a string (or use backsplash here) and for multi-line string constants (like doc strings). If the string is visible to use user and no debug message, use the i18n module _().
'a simple text' 'I can\'t believe how easy Python is' "I can't believe how easy Python is" """A multi- line comment.""" _('something to translate')
- Python's linebreak rules are not entirely straight-forward. Most lines cannot be broken without a backslash (\). The exception is for expressions with parenthesis and braces (both kinds), Python doesn't need back-slashes there. I think it looks better with extra parenthesis instead of backslashes.
- Freevo uses the python logging module. So there should be no print statements in the code, use the logging object. A set of files sgare a specific logging module name.
- Split import statements into up to four groups: normal python imports, kaa imports, freevo imports and imports in the current module (inside the same directory). Only import one module each line and do not import files not needed.