kpilot/Documentation/HOWTO-CODE.txt

Coding Guidelines for KPilot
============================

Of course we can wage war about what constitutes "good programming
practice". And agreeing on indentation style is difficult as well.
Below you can find the guidelines I try to stick to when writing
KPilot, split into "C++ Source Code" and "Header Files".

(For actual coding information and some information about how
KPilot works, see HOWTO-CONDUIT.txt)


C++ Source Code
===============

There are coding guidelines for KDE somewhere. I think they say
indent with 4 spaces, { on same line, } on separate line. I disagree,
so code I write -- and code I maintain -- slowly mutates to

	* Indent with tabs
	* { and } on separate lines
	* C comments only for the GPL header and KDoc stuff
	* C++ before the stuff they document, same indent level,
	  with possibly two extra lines with just // to set the
	  comment off from the code.

Whether or not anyone else follows is irrelevant, and I do try to
avoid gratuitous reformatting. Honest.

What I might do every now and then to get stuff "into shape" (and
I'd really appreciate it if you did so too before sending me patches)
is the following horrible invocation of indent:

indent -kr \
	--blank-lines-after-declarations \
	--braces-after-if-line \
	--dont-cuddle-else \
	--dont-line-up-parentheses \
	--honour-newlines \
	--space-after-cast \
	--brace-indent 0 \
	--case-brace-indentation 0 \
	--case-indentation 0 \
	--continuation-indentation 8 \
	--indent-level 8 \
	--tab-size 8 \
	--line-length 78

This doesn't yield "perfect" code but it's close to my personal ideal.
If this coding style gives you gas, just use your own favorite indent
invocation to change it all back.

NOTE: indent wreaks havoc with C++ class definitions in header files,
so it's best not to touch those with it.


Header Files
============

One thing we *do* need to agree on is how to protect
.h files from double-inclusion. In Qt and KDE there's:

	#ifndef QTCLASS_H
	#ifndef _KDECLASS_H

so for KPilot the convention will be

	#ifndef _KPILOT_FILENAME_H

where KPILOT is literal, ie. options.h is _KPILOT_OPTIONS_H and,
unfortunately, kpilotOptions.h is _KPILOT_KPILOTOPTIONS_H. This is
because the filename and the class don't always match up and not
every file contains a class of interest.


DEBUG Output
============

There are macros defined in options.h (which every source file
should include) that provide some uniform debugging output.
These are:

	* FUNCTIONSETUP - Use this at the beginning of every function
	  (or those that are vaguely interesting). This will print out
	  a call trace indicator when debugging is on. It also defines
	  a local symbol fname for use with DEBUG* below.
	* FUNCTIONSETUPL(level) - Use this at the beginning of a function.
	  It is like FUNCTIONSETUP but only prints if the debug level
	  is at least @p level. This avoids excessive debug output from
	  common functions.

For regular debugging output, use one of the three DEBUG* macros:

	* DEBUGLIBRARY in code in lib/
	* DEBUGKPILOT in code in kpilot/
	* DEBUGCONDUIT in code in conduits/

This sends the debug output to the appropriate debug area. A typical
debug output stream looks like this:

	DEBUGKPILOT << fname << ": "
		<< actual debug info
		<< endl;

Here, DEBUGKPILOT depends on what bit of code is being debugged; fname
is defined by FUNCTIONSETUP and takes care of proper indentation for
the call trace, the colon is for consistency and the actual debug
info can be whatever you want.

	Adriaan de Groot
	March 5th 2001
	September 5th 2001 (revised)