You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
113 lines
3.5 KiB
113 lines
3.5 KiB
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)
|