If you plan on contributing code to the Lucene4c project, this should be the first thing you read. If anything in this file is unclear, please ask about it on the project mailing list (c-dev@lucene.apache.org). TABLE OF CONTENTS * Directory layout * Coding style * Naming conventions * API documentation Directory layout ================ The top level of the source tree contains the following subdirectories: config/ holds random autoconf cruft, so as much of it as possible stays out of the way as possible. include/ holds public header files. src/ holds source code, broken out into subdirectories based on general category, like 'index' for code related to reading or writing an index, 'store' based on lower level code for reading or writing data on disk, 'util' for random utility code, and 'cmdline' for a command line interface. test/ holds code for the test suite, broken up into the same kind of subdirectories as the main lucene4c code. www/ holds the project web pages. doc/ holds files related to the project's documentation. Coding style ============ The project uses a style that basically boils down to the GNU coding style guidelines. Here's an example: char * function (char *arg, int otherarg) { if ((some_condition && otherarg) || another_condition) { arg = some_function (arg, otherarg); } else { do { arg = other_func (arg); } while (something); } switch (otherarg) { case 1: yet_another_function (arg); break; default: break; } return NULL; } If code does not conform to these guidelines then either comply with the local style if it's consistent about it or make it conform to the guidelines in a separate commit if it does not. Naming conventions ================== Lucene4c is implemented in C. Duh. This means that we don't have any automagical language provided namespacing mechanism, so we need to rely on naming conventions to avoid polluting the global namespace. All Lucene4c symbols that are exported from the final binaries or that appear in public header files must be prefixed with 'lcn' or 'LCN'. It is convention that macros are in capital letters, and functions lower case. If a function is declared non-static for technical reasons, not because it is intended to be consumed by users of the library, then it will contain a double underscore, for example 'lcn__cfs_istream_create'. This is to indicate to consumers that they are not allowed to call the function, as it is an internal implementation detail that could change at any time. Similarly, all public header files are named starting with 'lcn'. For readability reasons, all symbols are either all lower case, or all upper case, with underscores used to indicate breaks in words. API documentation ================= Lucene4c uses Doxygen (http://doxygen.org/) to generate documentation for its public APIs. This means that if you're adding to or making changes to any of the header files in the 'include' directory you need to keep the doxygen tags in the comments up to date. You can use the existing comments as a guide to the style we use, but in general we use a conversational style with arguments marked up with @a tags, bits of C code with @c, and so forth.