Hacking Conventions

This text is useful for developers who want to contribute to voc-get and wonder how to realize their work conforming to the rest.


Format your code well. It should be readable. If you wonder whether you code it readable, read it. If it looks cryptic, it is surely not.

If you have no idea how to format, use GNU Emacs.

Look in the written sources if you want to adjust your code.

Use many comments.


Routines like:

setting up bar ... done


setting up bar ... failed
foo: input/output error

or similar are very often used in voc-get. Currently you have to handle them by hand, but in the future there will be a routine that handles them.

First "setting up bar ... " is printed to stderr. Do not forget the blank after the dots! A good function for this is fputs or fprintf for formatted strings. Please use the gettext notation (_(foo) instead of foo) to be able to translate it later.

Then execute your code.

As soon as you know anything has failed, print "failed\n" to stderr. There may be several places where something may work wrong, so there can be several places in the code where you print that. You should also set errno and use

perror (program_name, ...)

to print it to stderr, too. After the user knows something has failed, you should abort the further routine execution. You should not exit the program directly because some cleanup functions have to be called first.

When everything has been done successfully, print "done\n" to stderr after. Even if your routine is always successful, you should print after everything was done. There are two reasons:

  1. A signal (e.g. SIGSEGV) may interrupt the process. It would be confusing if voc-get said everything had been finished.
  2. The routine may take a long time. If you printed immediately, there would be an empty line and the user would not know what voc-get is doing.

One hint: In some cases you have to fflush() stdout before and fflush() stderr after. This prevents some confusing mixed messages.

Return Numbers

define.h defines some return values. You should take a look at it first. It may be more up-to-date than this file. Anyway, here are some further explanations:


When you hack voc-get, set up your window manager, editor or whatever to display the word "modularity" as background image.

The user interface and the database access backend should be kept completely replacable. So do never use direct database access functions anywhere but in the database access part. Even if it is trivial, write a function that passes the call.

Even the currently existing code is not modular enough in my opinion. The parts for the different tasks should be made as independent as possible and the interface should also be made as simple and abstracted as possible. Even though it is a long time until the splitting, attempt to make the future work as easy as possible, please.