Code style guideline

LCDproc has been developed by many contributors over many years. You may find different programming styles (naming, indention, etc) in the source code.

When modifying an existing file, please take a careful look at its style and program continueing that style instead of mixing it up with another one even if it does not comply with the guidelines written below.

For newly added files the following guideline describes how source code should look like.

Note

All new submitted files will be passed through BSD indent to enforce the style described below.

File format and indention

  • Language: The programming language used for LCDd (server core), drivers and the lcdproc client is C. No other programming lanuage will be accepted.

  • File encoding: Files shall either encoded as UTF-8 or ISO-8859-1 and line endings shall be Unix type.

  • Line length: Lines of source code should be wrapped at column 80.

  • Indention: Tab indention shall be used (with tab width set to 8 characters). Only exception are switch labels which are indented a half tab (4 characters).

  • License: LCDproc is released under GNU General Public License version 2 (GPL v2) and every file shall have a standard copyright notice.

Naming conventions

  • Function names: Function names shall be lowercase. We do not use CamelCase. Multiple words are separated by underscore.

  • Variable names: We do not use Hungarian Notation. CamelCase may be used, but names shall beginn with a lowercase letter.

  • Constants: Constants shall be written in uppercase using underscore to separate multiple words.

Example 3.1. Names of constants, variables and functions

/* Constants */
#define KEYPAD_AUTOREPEAT_DELAY 500
#define KEYPAD_AUTOREPEAT_FREQ 15

/* Variable names */
MODULE_EXPORT char * api_version = API_VERSION;
MODULE_EXPORT int stay_in_foreground = 0;
MODULE_EXPORT int supports_multiple = 1;

/* Function names */
void HD44780_position(Driver *drvthis, int x, int y);
static void uPause(PrivateData *p, int usecs);
unsigned char HD44780_scankeypad(PrivateData *p);
  

Comments

  • All code comments shall be C-style comments (/* */). Comments spanning multiple lines shall have a star at the beginning of each line.

  • C++-style comments (//) may be used to comment out single lines of code to disable these lines. Larger blocks of code which shall be disabled should be wrapped within C-style comments or using pre-processor directives (#if ... #endif).

    C++-style comments shall not be used in general.

  • We use Doxygen to document our source code. Functions shall be documented using Doxygen-style comments (/** *). See Doxygen Manual for more information and how to use it.

  • If you carefully formatted a comment, you may use the special comment /*- */ (comment start is star minus) to prevent automatic reformatting. This usually applies to the standard copyright notice.

    Example 3.2. Standard copyright notice

    /*-
     * Copyright (C) 2010 Your Name <your_email_address>
     *
     * This file is released under the GNU General Public License.
     * Refer to the COPYING file distributed with this package.
     */
          

Statement style

  • Function declarations:

    Function declarations have their declaration and opening brace split accross two lines.

    Function names start in column one. The return type is placed on the previous line.

    There is no space between the function name and '('.

    Example 3.3. A function declaration

    /**
     * This is a Doxygen function description.
     *
     * \param y     The number of years
     * \param str   Pointer to a string containing X
     * \return      0 on success; -1 on error
     */
    int
    this_is_a_function(int y, char *str)
    {
    	code
    }
          

  • Operators:

    There shall be a space characters before/after an operator or assignment, except for increment (++) or decrement (--) operators.

    Example 3.4. Space around operators

    if (p->dispSizes[dispID - 1] == 1 && p->width == 16) {
    	if (x >= 8) {
    		x -= 8;
    		relY = 1;
    	}
    }
    
    x--;			/* Convert 1-based coords to 0-based */
    y--;
          

  • Function calls:

    There shall be no space between the function call and the opening '(' of the parameter list. Within the parameter list a space shall be after each parameter.

    Example 3.5. Function call

    lib_vbar_static(drvthis, x, y, len, promille, options, p->cellheight, 0);
          

  • Compound statements:

    Opening braces occur on the same line as the statement.

    Else statements: Else statements are placed on a line of their own, even is there is a previous closing brace.

    Opening and closing braces may be ommited on single line compound statements. However, if one part of an if-else-statement requires braces the other part shall have braces as well.

    Example 3.6. If-else with braces

    if (...) {
    	code
    }
    else {
    	code
    }
          

    Example 3.7. If-else with single statements

    if (...)
    	print();
    else
    	err = 1;
          

    Example 3.8. Other compound statements

    while (...) {
    	code
    }
    
    for (a = 0; a < max; a++) {
    	code
    }
    
    /* case labels are indented one half tab stop (4 spaces) */
    switch (icon) {
        case ICON_BLOCK_FILLED:
    	HD44780_set_char(drvthis, 6, block_filled);
    	break;
        case ICON_HEART_FILLED:
    	HD44780_set_char(drvthis, 0, heart_filled);
    	break;
        case ICON_HEART_OPEN:
    	HD44780_set_char(drvthis, 0, heart_open);
    	break;
        default:
    	return -1;      /* Let the core do other icons */
    }