Guidelines and HOWTOs/Code Checking: Difference between revisions
m →Suppressing false-positives: Get rid of horizontal scroll bar |
few things as ugly as scrollbars in note boxes =) |
||
Line 72: | Line 72: | ||
</code> | </code> | ||
{{Note| | {{Note|Using c-style (/* */) comments will ''not'' work. You must use C++ style (//) comments when noting tests to be skipped.}} | ||
}} | |||
===Compiler Warnings=== | ===Compiler Warnings=== | ||
In addition to the various Krazy tools, you can also get valuable assistance from the warnings that the compiler emits, especially if you enable additional warnings (per the documentation for your compiler), and also if you test with more than one compiler (e.g. if you can test on Linux with both GCC and the Intel compiler; or on Linux with GCC and also on Windows with the Microsoft compiler). | In addition to the various Krazy tools, you can also get valuable assistance from the warnings that the compiler emits, especially if you enable additional warnings (per the documentation for your compiler), and also if you test with more than one compiler (e.g. if you can test on Linux with both GCC and the Intel compiler; or on Linux with GCC and also on Windows with the Microsoft compiler). |
Revision as of 22:13, 7 February 2007
Code Checking
There are a lot of ways to find bugs in KDE code. Increasingly, KDE developers have started to use automated tools. You can use some of those tools to improve your own code.
The KDE 'Krazy' Checker
KDE developers have a simple set of tests that are collectively known as "Krazy". These tests were originally developed to be run as part of a larger set of tests on a machine known as http://www.englishbreakfastnetwork.org, or EBN for short. You can see the results of running the various tests on EBN (at http://www.englishbreakfastnetwork.org/krazy/).
You can also run the tests yourself. To do this, you need to obtain a copy of the code (from the kdesdk module, in ebn/krazy) and install them. You can then test either a single file (using the krazy application) or a whole tree, including subdirectories (using the krazyall application).
How Krazy works
The Krazy tests are essentially a form of static analysis - they check the source code, but not how it runs.
Krazy exists as a framework comprising a number of different test runners, and a set of plugins. The test runners are called krazy, krazyall, and krazyebn. The test runners just call one or more plugins on the appropriate code, and format the results for display.
At this stage, most of the test runners are written in perl, however one is written in C++ (using Qt) and it is quite possible to add your own tests, or to modify a test - all sources are provided.
Installing Krazy
Krazy needs to be installed before use. Krazy has two different ways to be installed - you can either modify the krazy/install.sh script and run it, or follow the instructions in the krazy/INSTALL.txt file. I recommend the second.
Using Krazy
Krazy comes with a particularly good man page, which gives you the various options and a usage example. The file is generated on installation. This is definitely recommended reading!
As noted above, there are three test runners - krazy, krazyebn and krazyall. If you are trying to check a single file, then krazy is the right tool. If you are trying to check a source tree (say, an application or a whole subversion module), then krazyall is more useful. krazyall doesn't have a man page, but you can get a list of the options with krazyall --help. You can also use krazy to get information on the various plugins, which can help you understand more about krazyall.
Remember that Krazy doesn't change your code - it only examines it. So you can safely experiment with running Krazy checks until you are confident that you understand what is happening.
Equally, that means that Krazy doesn't fix problems - it only tries to report them. Understanding what is being reported, and how to fix it, is up to you. You should also remember the KDE commit policy about not committing code that you don't understand. So fixing a spelling error in a comment is pretty safe, but blindly changing code to stop explicit constructor warnings from Krazy is not a good idea.
Suppressing false-positives
The Krazy tests are designed to minimise false positives (that is, alerts that do not represent real problems). However because most of the tests are conducted on a single line, there are some tests that might produce such a false positive. For example, code that does something like:
QString mystring;
mystring += "/";
will be flagged by the doublequote_chars checker, because it is more efficient to add a single char, as shown below:
QString mystring;
// note that we are using single quotes
// this is a char, not a char array
mystring += '/';
That same checker will produce a false positive for code that looks like:
std::string mystring;
mystring += "/";
You can suppress these false positives using a special comment format. To exclude a particular plugin from being run on a line of code, simply add a C++ comment containing the string "krazy:exclude=<plugin_name>".
Specifically, for this plugin use "krazy:exclude=doublequote_chars".
For example:
lenstr = "0" + lenstr;
becomes
lenstr = "0" + lenstr; // krazy:exclude=doublequote_chars
Compiler Warnings
In addition to the various Krazy tools, you can also get valuable assistance from the warnings that the compiler emits, especially if you enable additional warnings (per the documentation for your compiler), and also if you test with more than one compiler (e.g. if you can test on Linux with both GCC and the Intel compiler; or on Linux with GCC and also on Windows with the Microsoft compiler).