08 Apr 2011
Recently I’ve been working a couple of open source projects and as part of them I’ve been using some
libraries. In order to use a library though, you need to understand how it is designed, what function calls
are available and what those functions do. The two libraries I’ve been using are
Qt and libavformat, which is part of
FFmpeg and they show two ends of the documentation spectrum.
Now, it’s important to note that Qt is a massive framework owned by Nokia, with hundreds of people working on
it full-time including a number of people dedicated to documentation. FFmpeg on the other hand is a purely
volunteer effort with only a small number of developers working on it. Given the complicated nature of video
encoding to have a very stable and feature-full library such as FFmpeg available as open source software is
almost a miracle. Comparing the levels of documentation between these two projects is very unfair, but it
serve as a useful example of where documentation can sometimes be lacking across all types of projects, both
open and closed source.n So, lets look at what documentation it is important to write by considering how you
might approach using a new library.
When you start using some code that you’ve not interacted with before the first thing that you need is to get
a grasp on the concepts underlying the library. Some libraries are functional, some object orientated. Some
use callbacks, others signals and slots. You also need to know the top level groupings of the elements in the
library so you can narrow your focus that parts of the library you actually want to use.
Read More...
14 Mar 2011
Last year Nokia started developing their own Python bindings for Qt,
PySide, when they couldn’t persuade Riverbank Computing to relicense
PyQt under a more liberal license. While
developing DjangoDE I made the choice of which library to use
configurable. When running under PyQt everything worked fine, but when using PySide the program hung on exit.
Using gdb to see where it was hanging points to
QFileSystemWatcher, which has the following comment in
the destructor.
Note: To avoid deadlocks on shutdown, all instances of QFileSystemWatcher need to be destroyed
before QCoreApplication. Note that passing QCoreApplication::instance() as the parent object
when creating QFileSystemWatcher is not sufficient.
Read More...
07 Mar 2011
There are a number of tools for checking whether your Python code meets a coding standard. These include
pep8.py, PyChecker
and PyLint. Of these, PyLint is the most comprehensive and is the
tool which I prefer to use as part of
my buildbot checks
that run on every commit.
PyLint works by parsing the Python source code itself and checking things like using variables that aren’t
defined, missing doc strings and a large array of other checks. A downside of PyLint’s comprehensiveness is
that it runs the risk of generating false positives. As it parses the source code itself it struggles with
some of Python’s more dynamic features, in particular
metaclasses, which, unfortunately,
are a key part of Django. In this post I’ll go through the changes I make to the standard PyLint settings to
make it more compatible with Django.
disable=W0403,W0232,E1101
This line disables a few problems that are picked up entirely. W0403
stops relative imports from
generating a warning, whether you want to disable these or not is really a matter of personal preference.
Although I appreciate why there is a check for this, I think this is a bit too picky. W0232
stops a
warning appearing when a class has no __init__
method. Django models will produce this warning, but
because they’re metaclasses there is nothing wrong with them. Finally, E1101
is generated if you
access a member variable that doesn’t exist. Accessing members such as id
or objects
on a
model will trigger this, so it’s simplest just to disable the check.
Read More...
25 Feb 2011
Last week I had a discussion with my boss about the best way to communicate with my stakeholders about the
progress of any work that they have asked my team to do. The question basically became how much information
should be communicated during a project. The requirements and delivery phases obviously require close
communication, but what is appropriate while the developers are hard at working, churning out code? If, like
me, you are required to work a number of disparate departments then the people in the departments may want to
know what work is currently on your plate before they ask you to do something. What’s the best way to keep a
status board up to date?
Traditionally we have had a Bugzilla installation which was used to
store a record of almost every change we made. A
subversion post commit hook allows us
to link every commit back to a piece of work in Bugzilla. This works well for coding in an
issue-driven-development style, but does result in Bugzilla sending a lot of emails. Many of which are
completely irrelevant to people outside of IT. Indeed even people inside IT, but who aren’t directly linked to
that piece of work, don’t need to be informed by email of every checkin.
Recently we have begun to experiment with FogBugz. While
similar to Bugzilla it has a number of subtle differences. Firstly FogBugz is designed to be used in a
helpdesk environment so it provides the ability to communicate both within the team and with external
stakeholders from the same interface. This gives you the ability to communicate on two different levels, with
all the communication still being tracked. The second difference is that FogBugz is not known amongst the
people outside of IT. Not all stakeholder know about Bugzilla, but some do, and some can even search and reply
using the webinterface. With FogBugz we’ll take this ability away as, at least initially, only a limited
number of IT people will have access to the cases.
Read More...
16 Feb 2011
I’m using test driven development while
building my pet project, DjangoDE. A key part of an IDE is the syntax
highlighting of the code in the editor, so that’s one area where I’ve been trying to build up the test suite.
To test the syntax highlighter the obvious approach is to send the right events to write some code into the
editor the check the colour of the text. Although the QT documentation
is usually excellent, it doesn’t go into enough detail on the implementation of the syntax highlighting
framework to enable you to query the colour of the text. In this post I’ll explain how the colour of text is
stored, and how you can query it.
A syntax highlighting editor is normally implemented using a
QPlainTextEdit widget. This object provides the user
interface to the editor and manages the display of the text. The widget contains a
QTextDocument instance, which stores the text. To add
syntax highlighting you derive a class from
QSyntaxHighlighter then instantiate it, passing
the document instance as the parameter to the constructor. This is explained in detail in the
syntax highlighter example.
The document stores the text as a sequence of QTextBlock
objects. These store the text as well as the formatting information used to display it. You might think that
you can just call QTextBlock::charFormat
to get the colour of the text. Unfortunately it’s not that
simple as the format returned by that call is the colour that you’ve explicitly set, not the syntax highlight
colour.
Read More...