Searchmonkey coding style guide

From searchmonkey

This is only a guide to keep a consistant code base, and to aid readability, and comprehension of the code.

Contents 1 White space 2 Comments 3 Functions 4 Macros 5 Adjusting source code 6 Adjusting makefiles 7 Naming convensions 8 Navigation

White space

• Single line spaces should be used to group code together within a function.
• Double line spaces should be used to separate functions.
• if, do, while loops must be split to a minimum of 2 lines, regardless of how little is done. See examples.
• A two space nesting should be used to indent code for readability.
• No hard tabs, or spaces at end of lines.
• Functions are a minimum of three lines (if void) or four if return required. See example.
• Very long lines (i.e. >40 chars) should be broken at suitable points to aid readability.

if (test) {
  /* true */
} else {
  /* false */
}

do {
  /* loop */
} while (test);

gint my_function (variables)
{
  return 0;
}

Comments

• All comments should be of the form /* */.
• All functions should start with a multi-line comment, even if only one line long
• All comments should be placed before grouped statements, on their own line.
• Comments can be placed at the end of a beyond the semicolon of a code line when:
  • the code is a declaration (e.g. gint, gboolean)
  • the code is a preprocessor command (e.g. #define, #include, #if)
  • the code is a prototype (e.g. function, typedef)

/*
 *  My example multi-line comment
 */

/* My example single-line comment */

Functions

• Where possible, functions should be focused to a single well defined goal.
  • When large chunks of a function drift of topic, consider moving them to a separate function.
• Code re-use should be maximised with function use.

Macros

• Macros should only be used for constants, either text based or variable based
  • Consider replacing with a function if in doubt

Adjusting source code

• The function templates in callbacks.c should be kept to a minimum.
  • If large functions exist, consider creating a dedicated function.
  • No other code, declarations, should be added outside of the function templates
• All deleted widgets should also be deleted in callbacks.c/h
• All extra functions, headers and declarations should be put into a new c/h file
  • All new files should be focused to a specific programme area to aid code readability.
• No other c/h file should be modified by hand as they are owned by Glade.
• All headers should contain:

1. ifndef HEADER_FILE_NAME_H
2. define HEADER_FILE_NAME_H
3. endif /* HEADER_FILE_NAME_H */

Adjusting makefiles

• The only makefile to change are Makefile.am
  • Following a change, run autogen.sh
• The only configuration file to change is configure.in
  • This file contains the release version master

Naming convensions

• All macros and constants should be fully capitalised, with underscore between words.
• All names should be as descriptive as possible - but comprise may be necessary.
• All variable and function names should start with a lower case letter, and then have each subsequent word capitalised.
• All pointers should be prefixed with lower case 'p'.
• All typedefs should be prefixed with lower case 't'.
• All enum declarations should be prefixed with lower case 'e'.
  • Within enumerators all constants should be captilised, and take on the enum name too.
• All global variables should be prefixed with a lower case 'g'.

#define PRODUCT_NAME "searchmonkey" /* Example macro use */
gint gMyGlobal; /* Example global variable*/

enum {
  ECOUNTER_FRED = 0,
  ECOUNTER_BARNY,
  ECOUNTER_COUNT, /* Number of eCounters */
} eCounter;

typedef gint tMyType; /* Example typedef */

exampleFunction (gint firstVariable) /* Example internal variable */
{
  gint *pMyInternal = firstVariable; /* Example pointer */
  const gint MY_CONSTANT = 33; /* Example constant */
}

Navigation

Return back to the Developer Resources