Coding Style

If you want to make changes on the existing CAPS universe source code or extend it, then please honor the following rules:

• don't try to be smart in case of memory failures, always terminate the process instead and immediately. Use the caps_memory_failure_report() function to terminate.
• use tabs to indent the content, never spaces. Tabsize emulates 4 spaces
• there is no line length limit. But keep the lines as short as possible.
• no camelcase in function names and variable names! Use underlines to separate words in your function names or variable names
• prefer functions names with the style <component>_<scope>_<function>, e.g. caps_table_extend() instead of extend_table()
• if you change some code, always read the corresponding documentation again if you must adapt it to the change you made in the source code
• error messages should be created where they happen. If this would result into a useless error message (e.g. due to missing context), a different layer can create the error message instead
• debug messages are in English language only. They do not need any translation.
• debug messages are how they are called: they should help to debug the library in case of programming failures and thus are for the developer, not for the regular user. Keep in mind they are not included in the non-debug binary
• all other messages should be in English language as well, but additionally marked as translatable and thus, surrounded by the special NLS macro: _("your message")
• using message strings in a different context than printf() (for example string initializers in structures) may also need a translation and thus must be surrounded by the special NLS macro NLS_(<string>)
• programmer's failures using the library are reported in English language only. They do not need any translation.
• bad usage by CAPS components should always terminate the whole process - to force the developer to fix his code! Use the caps_developers_failure_report() function to terminate in this case.
• CAPS knows some level of verbosity, so be careful what level each of your messages should have. For a regular user a simple misbehaviour of CAPS should be detectable at the LIBCAPS_INFO level. If more strange things happen it should be detectable at the LIBCAPS_LOUD level, maybe at the LIBCAPS_NOISY level
• some of the rules here are from the Linux kernel coding style. Its a good idea to follow their guidelines (but not the 80 characters line length limit!)
• if a function always return successfully, they should have no return type. Use void to make clear how this function is to be used.
• references in the explaining text to parameters in the doxygen function headers should be prefixed with @p
• make use of the function attribute __nonnull to make clear, which parameter needs to be never NULL or which one are allowed to be NULL. Refer Function Attributes for other useful function attributes.
• add configuration macros to the generated config.h instead to the compiler's command line. The generated config.h file is always included as the first header file via the compiler's command line parameter -include. There is no need to include it explicitly in the source files.