Introduction

Working with an undocumented protocol also means developers need to take care of situations that can't be forseen. It's impossible to make guesses about error handling; e.g. having a list of things which the server may send differently. Code needs to verify it's boundaries, and warn (e.g. with kdWarning()) when received data can't be processed correctly.

Practices

The code is filled with assertion tests and strict validations of the data being parsed. This is required to verify whether the application communicates with the servers as it should. For example, an if-else-if always ends with a final else to trap unforseen situations. The P2P classes contain lots of code to detect the exact message type received.

Whenever possible, try to reproduce errors to test the code throughly.

To prevent crashes in unexpected situations, tests are added to detect null-pointers and warn appropriately. As rule of thumb:

  • Normal debugging messages are displayed with kdDebug().
  • Serious errors are displayed with kdWarning().
  • Debugging messages should only be displayed when the program is compiled in debug mode.
  • Warning messages may also be displayed by the final packaged executable.
  • Null pointers are checked using: if(KMESS_NULL(..)) return;.

Debugging features

When KMess is compiled in debug mode, the debug code between the #ifdef KMESSTEST and #ifdef KMESSDEBUG_... statements will be compiled. The macros for these statements are found in kmessdebug.h. The debug mode can be enabled in two ways: in KDevelop, select the 'debug' build configuration.

For manual compiling, use: 

CXXFLAGS="-g -ansi -pedantic -Wall" ./configure --enable-debug-output --enable-debug=full

Most of the time the following is also good enough: 

CXXFLAGS="-g" ./configure --enable-debug-output

The debug mode adds:

  • filenames and line numbers to crash dumps.
  • filenames and line numbers to the KMESS_NULL macro output.
  • assertion tests to most functions.
  • verbose messages so code execution can be traced.
  • a dialog to analyse the network traffic.

A special KMessTest class can be used to create use-case tests. This class can be activated by both disabling and uncommenting the various lines in main.cpp.

There are also some small stand-alone debugging tools in the debugtools folder of SVN.