Commits and coding style

Why this document

In order to have good quality in our software we must make it consistent, as easy as possible to read, make sure we can spot issues as quickly as possible and, eventually, make issues easy to fix (or avoid them at all). This document provides some guidelines about the minimal rules that apply both to external patches and to our members commits.

Coding Style

Writing code for some, maybe many, is considered a form of creative activity and as such it could be made into art as you can with painting, composing music or sculpture. We are humble enough to consider our code not that good and we'll strive to make it readable. The coding style reflects that:

Indentation rules:

• Use only spaces, tabs are forbidden. This way doesn't matter which editor you are using, the code will always look the same
• The lines should be 79 columns at most. There is still people using 80cols terminals around there, mostly because they use to have at least 2 or 3 source windows next to each other.
• Indentations must be 4chars.

Comment rules:

• Every new file should have a doxygen header explaining what the file is supposed to do
• You can be terse while commenting the code, but please give some hints about non self describing code (feng has plenty of it being either clarified or commented). That helps refactoring and debugging.
• Headers must have doxy comments and proper grouping
• Doxygen syntax must be the javadoc like one.

Syntax:

• If a function is used just internally make it static and avoid prototypes, just declare them in the right order. This makes the line count lower, helps debugging and let you avoid having to namespacify every function to avoid casual clashes.
• Try to avoid convoluted expression, e.g. use switches instead of if-chains
• Don't be afraid to use goto if you need to error out: just put your cleanup lines at the bottom of the functions with a label and goto it.

Commit/patch rules

Common rules:

• Commits (and patch) should be small, self contained don't break the compilation.
• Before committing or submitting a patch always make sure that the software builds and runs (some automated tests will be provided soon).
• Do not mix functional and cosmetic changes in the same submission.
• The comit message should be terse but should describe the purpose of the patch, don't be afraid to be less than serious, coding should be fun!

git commit -m "..." -a

git  commit -m "Cosmetics" files/that/I/just/reformatted
git-commit -m "Now with double coffee and theora bits" mediathread/*

Patch rules:

• patches should be in unified form (diff -u), you are advised to use git patch facilities since it makes sending and applying patches quite easier.
• Please give a verbose explanation of what it tries to do and why.
• Send them as plain text, compressed tarballs will be rejected.