Wednesday, May 13, 2009

Open Qt repository and hidden gems

On Monday Qt Software launched the public repository for Qt. Already there are more then a dozen patches waiting for review in the merge request list and no doubt there will be many more. To help developers submit patches that are higher quality and more likely to be accepted a number of documents have been published on the Qt wiki. Beyond the wiki in the source repository there are new things that could not previously be found in the snapshots or releases. With so many new things I wanted to highlight a few of the items I found most interesting.

Qt Coding Style Followed not only by Qt, but by other projects such as Arora and applications in KDE. Having a common coding style makes code easier to read and review. In the past few years I have seen many applications adopt this style and I look forward to seeing the usage grow.

Api Design Principles An updated version of the old Qt Quarterly article Designing Qt-Style C++ APIs from the first paragraph: "This document tries to summarize the know-how we've accumulated on designing Qt-style APIs. Many of the guidelines are universal; others are more conventional, and we follow them primarily for consistency with existing APIs."

The Little Manual of API Design by Jasmin Blanchette’s In the wiki page for Api Design Principles you find a link to the this pdf which is now public. This first rate book should be mandatory reading by any programmer. While many of the examples are from Qt and in C++ most of its ideas apply beyond Qt and C++. Rather then doing it a disservice and trying to describe it, here is the table of contents which gives a good overview.

1 Introduction 5 
2 Characteristics of Good APIs 7 
2.1 Easy to learn and memorize . . . . . . . . . . . . . . . . 8 
2.2 Leads to readable code . . . . . . . . . . . . . . . . . . 9 
2.3 Hard to misuse . . . . . . . . . . . . . . . . . . . . . . 10 
2.4 Easy to extend . . . . . . . . . . . . . . . . . . . . . . 12 
2.5 Complete . . . . . . . . . . . . . . . . . . . . . . . . . 13 
3 The Design Process 15 
3.1 Know the requirements . . . . . . . . . . . . . . . . . . 15 
3.2 Write use cases before you write any other code . . . . . 15 
3.3 Look for similar APIs in the same library . . . . . . . . 16 
3.4 Define the API before you implement it . . . . . . . . . . 17 
3.5 Have your peers review your API . . . . . . . . . . . . . 17 
3.6 Write several examples against the API. . . . . . . . . . 18 
3.7 Prepare for extensions. . . . . . . . . . . . . . . . . . 18 
3.8 Don’t publish internal APIs without review. . . . . . . . 18 
3.9 When in doubt, leave it out . . . . . . . . . . . . . . . 19 
4 Design Guidelines 21 
4.1 Choose self-explanatory names and signatures . . . . . . . 21 
4.2 Choose unambiguous names for related things . . . . . . . 22 
4.3 Beware of false consistency . . . . . . . . . . . . . . . 23 
4.4 Avoid abbreviations . . . . . . . . . . . . . . . . . . . 25 
4.5 Prefer specific names to general names . . . . . . . . . . 25 
4.6 Don’t be a slave of an underlying API’s naming practices . 26 
4.7 Choose good defaults . . . . . . . . . . . . . . . . . . . 27 
4.8 Avoid making your APIs overly clever . . . . . . . . . . . 28 
4.9 Pay attention to edge cases . . . . . . . . . . . . . . . 28 
4.10 Be careful when defining virtual APIs . . . . . . . . . . 30 
4.11 Strive for property-based APIs . . . . . . . . . . . . . 31 
4.12 The best API is no API . . . . . . . . . . . . . . . . . 32 

Codeing Conventions and Binary Compatibility Workarounds Two good documents that walk through a number of issues that Qt has to deal with being a library that is used on many platforms and compilers. An interesting read for anyone who uses C++ or Qt.

Autotests and Benchmarks After several years of discussing it, the Qt autotests have finally been published. Everyone in KDE can finally checkout how class Foo is tested and when writing patches for Qt an attempt should always be made to write a matching autotest. See some interesting usage of qtestlib and get plenty of example of how to test gui widgets. For those who are writing their own tests check out my QAutoTestGenerator tool which generates test stub files for you to help get you started. Hopefully having this large set of tests open will encourage more Qt projects to have tests. For those who are using Git and qtestlib I have written a git hook that can be found in the Arora repository that will run the matching autotest for files you change to check for any regressions before committing.

The full commit log for Qt While in the past the qt-snapshot git repository gave a one day granularity the new repository includes every commit with the commit log. The other day while tracking down the QTemporary bug in 4.5.1 I wrote a little test application and Thiago used git bisect to find in twenty minutes the exact commit that had caused the breakage.
git bisect start HEAD v4.5.0 -- src/corelib/io
git bisect run sh -c 'LD_LIBRARY_PATH= make sub-corelib && (ulimit -n 250; /tmp/qfile-bug/qfile-bug)'
With the full commit log tools like bisect and blame become even more useful for inspecting the Qt source code.

With the Qt source code on Gitorious it will be easier for developers that need a bug fixed to help contribute and get it fixed in Qt faster. Those who use Qt and want to understand how something works or why it was developed in a particular way will be able to more easily explore the code base. And maybe KDE can even remove the legacy qt-copy. No doubt many good things will come out of the open Qt repository and I look forward to seeing what the community contributes.

Popular Posts