development:db-devel - Kamailio (OpenSER) Wiki

– Kamailio SIP Server –

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

====== Guidelines about developing new database modules ======

===== Error checking =====

Its absolut necessary to check for the validity of your input parameter. Otherwise you'll crash on the first null pointer that you get. The job of the database modules is to provide a API for other modules, thus offer a service. The client code will be invetable try to do stupid things because we're not living in a perfect world.

So please don't hide your input checks behind some #ifdefs like "XXX_EXTRA_DEBUG" or something similar. In general there should be no new #ifdefs introduced for (in my opinion stupid) things like this. Nobody will configure them, instead the default will be used. Every #ifdef increase the complexity, the number of code paths that needs to be tested, in the end the number of bugs. So again, instead of shifting the responsibility to the user or packager, try to find a solution that works generally.

===== Error logging =====

Its really essential to output meaningful error messages with the correct log level for problems that causes operations to fail. Its not feasible to run a production server with activated debug only to get information about the reason why this certain query failed. Error logs provides important information that is needed from API users, so please use LM_ERR and don't hide them under thousands of other meaningless debug messages. So again, if you return a failure to the client of the API, log also an error with a meaningful message that is understandable by the admin or user that don't wade through the code regularly. 

===== Code structure =====

Maintaining all this bunch of modules is much more easier if everybody tries to conform to a common coding style and structure. So please use the same conventions in your code that are used in other database modules, even if you don't like them. This applies to function definitions, parameter names, error logging, debug messages, even to the practise of memory management.

To be fair, this is only possible to a certain degree, but e.g. all SQL based driver library interfaces are somewhat similar, there was no reason in the first place why the SQL modules should differ that much. An additional benefit in having the same error and debug messages in different modules is 
that this really makes debugging and the bug fixing process easier. I know that you only care about "your" driver during development, but you should 
also care about the whole project. 

===== Documentation =====

Yes, nobody likes to write documentation. But the absolute minimum to understand any non-trivial foreign code is to have a comment block at the 
function definition describing in a few sentence the purpose of the code, the input parameter and return value. Its also important to describe why you do certain things in your code, e.g. because of some driver requirements, some bugs etc.. No comments in the code slows down the maintainance, more bugs will be introduced on changes and so on.

Trace: • private-memory-size • kamailio-devel-from-git • installation • index_of_openser_1.0.x_fifo_commands • dialog-module-design • kamailio-3.0.x-from-git • html-documentation