diff options
Diffstat (limited to 'kpilot/Documentation/HOWTO-CODE.txt')
| -rw-r--r-- | kpilot/Documentation/HOWTO-CODE.txt | 112 |
1 files changed, 0 insertions, 112 deletions
diff --git a/kpilot/Documentation/HOWTO-CODE.txt b/kpilot/Documentation/HOWTO-CODE.txt deleted file mode 100644 index 99c093c6..00000000 --- a/kpilot/Documentation/HOWTO-CODE.txt +++ /dev/null @@ -1,112 +0,0 @@ -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) |