Coding Guidelines

From Buzztard

For editing source-code we use jEdit and Anjuta, but feel free to use any editor you are comfortable with.

[edit] Indentation

Eventually we will put an indent script into the cvs tool chain. For now, have a look at our code and try to write new stuff in the same way. It uses 2 spaces for indentation.

We got rid of all the tabs ;) with this shell one-liner:

find . -name "*.[ch]" -exec sed "s/\t/  /g" -i {} \;

We may rethink this decision based on this nice article.

[edit] Source documentation

We have decided to use gtk-doc for the documentation as it better fit with the gobject architecture. Read this how-to article for a introduction.

The other candidate was doxygen.

When documenting the API, add the comments to the *.c files and not to the *.h files.

1. Changing header files forces recompilation of the whole project.
2. We want to keep the headers small
3. Developers should use te API docs and not needing to look into the sources so much.

[edit] Naming conventions

Please try to follow the gnome coding style guides.

[edit] CVS commit message format

Like other GNOME project we use [prepare-ChangeLog.pl] to maintain ChangeLog entries. Additionally we use Tim Müllers Version of David Schleefs [cicl] tool to commit changed files and [diffcl] to preview the changes.

[edit] prepare-ChangeLog.pl

This script generates a new ChangeLog entry for the developer. It needs the email address set in an environment variable. Add the following line to your $HOME/.bashrc or similar.

export REAL_NAME="Stefan Kost"
export EMAIL_ADDRESS=ensonic@users.sf.net

When a task is finished, just run

prepare-ChangeLog.pl
vi ChangeLog

You may use your preferred editor instead :). Add comments below the files to describe the changes. Do not just write "Fix a bug", try to be specific. You can include sf.net bugnumbers, by prefixing the number with a '#'. If the log entry lists files you don't want to commit, please remove them. For one example having different gettext versions among developers can cause po files to apprear in the log entry. If you have not change the po files yourself, remove the lines to avoid unnecessary commits.

To commit your changes use cicl.

[edit] cicl and diffcl

Cicl is commit-changelog. Instead of doing

cvs ci .

now just run

cicl

This will simply commit all files listed in the top ChangeLog entry. The same way you can use diffcl to get a diff of the current changes (e.g. to sent them as a patch).

[edit] CVS tag/branch names

Developments always happens in HEAD. For some events we need to tag a snapshot. It would be good to agree on a scheme for tag names. We need tags to mark

• releases
  • RELEASE_0_1
• pre-releases
  • RELEASE_0_1_rc1
• points where we branch, when using a new (incompatible) backend API
  • SWITCH_GST_0_8__0_9
• points where we merge (do we merge?)
  • MERGE_SWITCH_GST_0_8__0_9__HEAD

This is the command line to tag the files:

cvs tag -cR SWITCH_GST_0_8__0_9