ROWS coding style conventions

These coding conventions are designed to give code written for ROWS a common styling as well as a very neat and readable appearance. They are only guidelines: if you can make a piece of code look neater by disregarding them in some instances, that is perfectly acceptable. They are currently designed for C-like languages (C, Java, C++ should be able to follow the conventions almost to the letter) - other style languages will need their own conventions, which will probably be designed when ROWS interfaces to these libraries are created.

Naming conventions

A ROWS component generally consists of 3 files - 2 headers and 1 code. The names of each of these files should start with the major library/program name they are for (ROWS for ROWS core components, IMPULSE for components specific to Impulse applications, etc) and be followed by the minor component name (ie ROWSwindow.h, ROWSwindow.c) or 'int_' followed by the component name (ROWSint_window.h) for internal definitions of opaque data types (this is mainly the widget internal data structures). If there is a requirement for further files, for example if the component is very large and best split across several source files, the new files are distinguished with a unique name after an underscore (eg ROWSwindow_create.c).

Function names follow a similar convention - eg ROWS_window_create. Note that there is now an underscore separating the minor component name from the function name, and the function name has three parts separated by underscores (major component, minor component and component function name). If the function name consists of several words, these are usually separated by further underscores (ROWS_brush_fill_arc). Data types are named in similar fashion, although if there is a major data type, such as a widget type, this can be called using simply the major & minor component names (ROWS_brush, ROWS_window, etc). Note that usually these are found in the header files ROWSbrush.h, ROWSwindow.h, with few exceptions (the general functions in ROWS.h).

Private functions and data types that have to be declared global rather than static should be prefixed with '_p_' followed by component names (eg _p_ROWS_widget_notify_list).

Code style conventions

General conventions

Spelling is British English!

Usually, code can be divided into distinct sections, both those natural to the language (introductory comment, #include statements, data definitions, code, etc) and those specific to the . The divider shown below is used to divide these sections:

/* ======--------====== */

Wherever sensibly possible, lines of code should be kept under 76 characters wide so as to fit easily on most terminals. Multiline comments should begin with a single line containing '/*', end with a line containing ' /*', and each line of comment should begin with the ' *' character (with spaces so that all the *s line up). Where names of variables sensibly group, they should be aligned so that the first character of each name is in the same column (the * pointer indicator is not the first character of the name) - examples of such groupings are the parameters of a function, related values in a struct or union and variable declarations at the beginning of a function. Function parameters are separated by newlines to facilitate this. All source and header files should begin with the licensing information (the MPL in the case of ROWS). Finally, indentation is usually by 2 characters.

Code example:

/* ======--------====== */
static void ROWS_window_setup(ROWS_widget *widget, _p_ROWS_window_data *data); static int window_ID = -1; static int window_type = -1;
ROWS_widget *ROWS_window_initialise(int id, char *title) { ROWS_widget *widget; _p_ROWS_window_data *data;
if (a==b) { printf("bar!\n"); }

Header files

These should start with a macro definition to protect the file from multiple inclusions (eg #ifndef __ROWS_box_h, #define, ...), followed by a section divider, followed by any #includes that this header file requires, followed by another section divider, followed by type definitions, followed by a further section divider, followed by function definitions. Further section dividers may be used to group functions, and this strict style is not really important in the ROWSint prefixed headers. The order may be changed where necessary (for example type definitions may be needed before a #include is possible). Generally header files should have a comment describing their purpose towards the top.

Code files

Once again, sections divided by the section divider, although more liberal use of the divider should be made between function groups. Code files should start with #includes (in the order standard library includes, third-party includes, ROWS includes) followed by global variable declarations, followed by static function definitions, followed by static variable defintions, finally followed by the function code itself.