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.

Coding

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.

done/failed

Routines like:

setting up bar ... done

respectively

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:

• If you have a function that either suceeds or fails, you should choose int as return type. Return the self-explaining values RETURN_SUCCESS respectively RETURN_FAILURE. According to the usual behaviour of library functions, RETURN_SUCCESS is 0 and RETURN_FAILURE is -1, so do not think a function succeeded if it returns a true (i.e. not 0) value. Always compare with RETURN_SUCCESS or RETURN_FAILURE. RETURN_FAILURE makes always expect errno to be set, so please do so.
• If your function returns a NULL pointer, please set errno, too. NULL pointers always indicate an error.
• RETURN_FAILURE may also be useful for functions that usually return positive integer values. Make them return signed variables that are RETURN_FAILURE on failure. In this case you should not compare with RETURN_SUCCESS in the calling function.
• Some functions may return whether something is true or not, where the latter case does not mean execution failure. C99 specifies the bool type, but because this triviality is not always supported, voc-get implements its own BOOL, TRUE and FALSE in uppercase letters. Because TRUE is usually not 0 and FALSE is, you can call the returning function directly in an if statement safely. BOOL is usually int because that works fastest. But theoretically, every integer type should work.

Modularity

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.