Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 112 insertions, 0 deletions

diff --git a/kpilot/Documentation/HOWTO-CODE.txt b/kpilot/Documentation/HOWTO-CODE.txt
new file mode 100644
index 000000000..99c093c67
--- /dev/null
+++ b/kpilot/Documentation/HOWTO-CODE.txt
@@ -0,0 +1,112 @@
+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)