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.
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.
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:
One hint: In some cases you have to fflush() stdout before and fflush() stderr after. This prevents some confusing mixed messages.
define.h defines some
You should take a look at it first. It may be more up-to-date
than this file. Anyway, here are some further explanations:
intas 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.
booltype, but because this triviality is not always supported, voc-get implements its own
FALSEin uppercase letters. Because
TRUEis usually not 0 and
FALSEis, you can call the returning function directly in an
intbecause that works fastest. But theoretically, every integer type should work.
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.