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 in KMess

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: 

./configure --enable-debug-output --build-type=debugfull --build-dir=build-debug

which is identical to: 

mkdir build-debug
cd build-debug
cmake -D CMAKE_INSTALL_PREFIX=`kde4-config --prefix` -D KMESS_ENABLE_DEBUG=1 -D CMAKE_BUILD_TYPE=debugfull ..

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 --runtest parameter to run tests from the KMessTest class.

Other debugging tools

In SVN there are also two interesting folders:

  • debugtools contains small stand-alone tools, for example to decode context fields / client capabilities.
  • kmesstestserver contains a WLM server implementation.