Spring: cleaning up

Its the time of the year again, spring. Meaning, time for the big clean up. Not the house of course, we leave that to the people feeling themselves called to clean houses. I’m talking about code. Over time we, as in developers, come to the conclusion that this neat API we wrote is not as neat as it looked in the first place. So we redesign our API and BIC lovers as we are, mark methods that should not be used anymore as deprecated.

This is of course very nice, but how do we actually get an overview of the methods that are marked as deprecated, more important how do we get an overview of how often deprecated methods are still in use? Well, kdevcpptools to the rescue. As I blogged before I worked on a C++ query and transformation engine for KDevelop as part of my Msc thesis. After an awesome lot of stabilization work of Milian "code monkey" Wolf, the plugin really is in quite a nice state at the moment and I would say quite usable. In the rest of this post I’ll show how to use it by taking kdepimlibs as an example.

The first thing to do is to create a query file containing the queries for the deprecated functions. The query (and transformation) file is a relative simple XML file describing the queries and optionally transformations. There are some example files in the git repository, but don’t jump to that yet as I want to show a cool feature Milian implemented.  Lets find the deprecated functions first. Okay, no fancy tools for that (yet?), so just a plain ack-grep on "KDE_DEPRECATED" in kdepimlibs. This gives me a lot of files containing this macro. We startup KDevelop and create a new empty query file with the following content:
?xml version="1.0" encoding="UTF-8"?
  porting-description
    queries
   /queries
  /porting-description

(Yes, the formatting sucks, don’t know how to make drupal output XML in a sane way). Next, open one of the files that showed up in the results of your grep and go to one of the deprecated functions. Make sure that you have the kdevcpptools tool view enabled and right click the function. The context menu shows you this wonderful option: Copy XML query:

Copy the resulting XML from the clipboard into your file and there you go, its that easy. I did this for whole kdepimlibs, you can find the file here. First observations: we’ve 47 deprecated functions in whole kdepimlibs and we really have  a shitload of date string formatting functions in kdepimlibs, so…. if you need one…..

When you’re done putting in your queries in there, you can open the XML file in the kdevcpptools plugin. This enables you to query a project. I did this for kdepim, meaning, the result I get are all uses of deprecated functions from kdepimlibs in kdepim. This result was so to say pleasantly surprising. Have a look at the next picture:

In the lower part of the screen you see an overview of the results for kdepim. Vertical axis are files horizontal axis are queries. First observation here: there are surprisingly few uses of deprecated functions. (Note: we’re only talking here about functions, explicitly marked as deprecated). Second observation: though not particularly interesting for such few results, the curve you see in the total column looks promising. I.e. most uses in only a small part of the files. Meaning, only a couple of files need "major" changes. This must of course be seen in perspective, this reasoning is not particular interesting when you only have seven hits for a ~700KLOC code base. Would you had have a similar curve for ~8000 uses this would of course already make a lot more sense. The curve in the total column will actually tell you how the migration work is distributed over the code base you’re querying.

So, my initial idea was to do a bit of clean up in kdepim but it turned out that this is hardly needed with respect to this specific area. The good thing is that we now know that it isn’t needed. This means that as soon as KDE5 development kicks off we can get rid of these deprecated methods without a lot of work (in kdepim at least). I’d really encourage anyone interested in these kind of analysis on his/her code base, either from a lib perspective like I did, or from an application perspective (anyone interested in building up a query file for qt3support and query the various kde modules for it?) to checkout the plugin[1] and play with it. You can find me and Milian in KDevelop if you need help on getting started with the plugin.

Next step is using the transformation engine to do (at least part of) the migration work automatically. I hope to blog about that soon. But first a thesis to finish…..

[1] http://gitorious.org/kdevcpptools