Archive for the ‘Projects’ Category

Closing the feedback loop

In Programming, Timeline on July 4, 2010 at 2:41 PM

I have recently spent some time reading the book Working Effectively with Legacy Code by Michael Feathers. I find it interesting because it describes techniques for making bad code better.

Feathers defines legacy code as code that does not have tests and further argues that code without tests is bad code. If you believe in this statement and have the intention of converting a piece of legacy code to code that is tested you face a problem: legacy code is often hard to test because it often has many dependencies that are hard to construct in tests. The main part of the book describes techniques for solving this problem: getting tests in place for legacy code.

In one of the introductory chapters the author talks about the effect that feedback has on changing code. Feedback here means the time it takes before you see the effect of a change in the code. If you have to manually perform some action in a GUI to see the effect of a change it will probably take you a minute ore two. If you have to do that many times you will perhaps become frustrated and bored. If you instead can run a set of automated tests to ensure that your change is good, the thing that you are working on can be implemented faster. The shorter the feedback loop, the better.

If you work in this modify-test fashion, you are likely leaving your editor and pressing a button to run your tests after you have finished an edit. In the book, Feathers suggests that this cycle can be shortened by running the tests continuously. In particular, the tests could be run as soon as you type a key in your IDE. That sounded interesting to me so I decided to implement a simple application for use in the Timeline project that do something similar.

The application is a small GUI application that looks like in the pictures below. When you start it, it will run all tests (using the console based test script) and display the output. If all tests passed the top part will become green, otherwise it will become red. The special thing with this application is that it monitors the file system for changes and whenever it detects a change, it runs the tests again. So as soon as you hit save in your editor, the tests will run again automatically. That way you never have to leave your editor to find out how the change you made in the code affected the system. (Of course this relies on writing tests as well as code.)

The application is running the tests on start-up. It will also re-run them every time it detects a change in a file.

The application ran the tests and they all passed.

The application ran the tests and some of them failed. You can quickly edit your code to try to fix the errors, and when you save, you find out if you fixed them or not.

I will start using this tool when working on Timeline and see how it affects my productivity and code quality.


Unit testing revisited

In Programming, Timeline on January 4, 2010 at 9:57 PM

Every time I make a new release of Timeline I get a little nervous. Nervous that the program will not work or do something unexpected. One obvious activity that helps find bugs in the program is testing. Usually when I work on a new feature I try it out as I go and make sure it works. The problem is that I can’t say with confidence that other features still work: features I haven’t touched for this release or haven’t used in a long time.

One solution is to test all features before every release. That is a tedious job. Especially when you make releases often as we do (once a month). I have experimented a little with unit testing but find it quite difficult. We only use it in a few places to ensure correctness of a few functions. A podcast and an article pushed me intro trying unit testing again and also working in a test driven development fashion.

The podcast

In FLOSS Weekly 87: Extreme Prgramming With Kent Beck topics such as extreme programming (XP), test driven development (TDD), pair programming, and design patterns are discussed. It does a great job of demystifying these buzzwords and makes you understand the core ideas behind them.

In particular I like the fact that they go back and talk about a well designed program as one that has low coupling and high cohesion. Later they talk about how techniques such as TDD help achieve that.

The real eye-opener for me after listening to this show was that the purpose of writing unit tests is not only to test the correctness of a function: it is also designing your code in such a way that it can be tested. And if it can be tested it probably has low coupling and high cohesion which in turn makes it a well designed program. Kent mentions in the show that having the correctness of a function tested is just “a really nice side effect” of writing unit tests.

The article

Now I had a slightly more positive attitude towards unit testing and I wanted to try it out in practice by refactoring some code for Timeline. One thing that is typically difficult to test automatically is GUIs. In Timeline there is at least one GUI component that is quite large and contains much logic. I would be really happy if we can test it automatically somehow.

Browsing the net for answers I came across this excellent article: The Humble Dialog Box by Michael Feathers (found via How can I unit test a GUI?). It describes a totally different approach to designing GUIs that really fascinated me. You remove almost all logic from the GUI and instead put it into another object which can much more easily be tested.

The experiment

I decided to try the idea with a humble dialog box on the category editor in Timeline. It is a very simple dialog which makes it suitable for trying this approach.

For those of you interested, you can read the source code for this dialog before and after (source code for test).


Although the overall length of the code increased I think the separation between the GUI and the controller (the logic that was previously in the GUI) is slightly more readable. Most of the code fore the GUI is now extremely simple. So the increase in code size is not such a big issue I think. It also feels quite nice to be able to test the simple logic of this dialog.

I am still not convinced that unit testing is the answer to all problems regarding ensuring high quality. And maybe that is not the case either. After all it is just one means to get high quality code. I think doing code review is another good means to that same end. I might try this approach again on a more advanced dialog.

A side note

The Flawed Theory Behind Unit Testing (from Michael Feathers’ Blog) expands on the idea that unit testing is just a means to an end where the end is high quality code. From the post:

In the software industry, we’ve been chasing quality for years.  The interesting thing is there are a number of things that work.  Design by Contract works.  Test Driven Development works.  So do Clean Room, code inspections and the use of higher-level languages.

Go read the whole article if you are interested in knowing what it is that makes the above mentioned things work.

Multiple Mercurial repositories on SourceForge

In Timeline, Tutorials on October 1, 2009 at 8:19 AM

When SourceForge announced support for multiple Mercurial repositories I was eager to try it out for our project. I found the documentation on the wiki a bit lacking and I had to ask around on the IRC channel for help. Below I present the problem I had and the solution to it.

After reading Creating Multple Repositories on the Mercurial wiki page I had successfully created multiple repositories and was able to access them. I also read Mercurial permissions management and granted another member of my project write access. It turned out though that this was not enough.

You also need to change the permission on the Mercurial repositories using the interactive shell service so that the group also has write permissions:

chmod g+w .hg .hg/* .hg/store/*

And if you have any files under .hg/store/data you also need to assign the same permissions to them.

Even if you assign write permission to the group, only the ones that you granted access in the admin interface will be able to write to the repository. (The guys on the IRC channel told me that only the ones granted access in the admin interface will get the Mercurial mount.)

I think it would be good if this information was available on the SourceForge wiki. But in the meantime, I publish it here.

A new help system

In Timeline on September 9, 2009 at 6:59 PM

The last couple of days I have been working on a new help system for Timeline. Instead of having a single user manual document which is hard to navigate, the new help system is more like a wiki with many small pages covering specific topics. All pages can also link to related pages. This approach has some advantages over a singe user manual document:

  • It is easier to write a help page about a topic because you do not need to figure out where in the manual to put it or be concerned that it will not fit the structure of the manual
  • It is easier for translators to translate a short isolated page instead of a long manual
  • It is easier for users to find information because you can organize the pages in any way you want: popular help topics can be linked to on the first page for example

The new help system is available in the development repository now and will appear in the 0.5.0 release scheduled for October 1, 2009. I believe it will make working with help easier for everyone.

From idea to reality

In Timeline on September 2, 2009 at 12:49 PM

Many times I’ve had ideas for programs to write: sometimes because I felt the need for a particular application and other times just because the programming task seemed challenging. Many of the ideas I’ve had never turned into more than incomplete drafts or half-broken programs. When I started The Timeline Project on of the goals was to actually finish this project and not stop halfway because of lack of motivation. Below I continue to list and discuss what I think are the most important reasons why I succeeded.

I made it public and real

Before I wrote a single line of code I registered the project on SourceForge. That forced me to write a description for the project: now the whole world, or at least all the SourceForge visitors, would know the purpose of my program. Since I decided to make this a free software project, everyone would also be able to see everything I did. Suddenly it was not just a couple of files sitting on my local harddrive. This was something real that I could tell people to have a look at.

I had guidance

I had no previous experience in neither running a free software project nor participating in one. I figured the best way to learn was to just to start a project. Without the guidance from Producing Open Source Software I don’t think I had been as successful. It was particularly useful for figuring out what documentation to write and what tools to use. (SourceForge also provided many of the tools mentioned in the book.)

I was not alone

Right from the beginning I involved another person in this project: my dad. Now everything I did in terms of coding and documenting also had to be comprehensible to someone else. This also made the project feel more real. Another benefit was that we could discuss problems and solutions with each other.

Other people got interested

Despite the reasons for success mentioned above my motivation still dropped at one point. Mostly because I felt the application would not be useful for me. That changed one day when an unexpected email reached my inbox: someone was interested in using Timeline. That person made me believe in the idea again and several improvements were made to the program after that.

Writing good documentation

In Timeline on August 31, 2009 at 9:54 AM

One subject that interests me is how to write good documentation. Trying to explain to someone else what is perfectly clear in your mind is a challenging task. In The Timeline Project I get to practice writing many types of documentation such as comments in source code, user manual, instructions for volunteers how to participate, and replies to emails on the mailing list.

I am interested in improving my ability to write good documentation and I think one prerequisite is good writing skills. Therefore I was browsing the web for podcasts about writing and I found a website called I’d Rather Be Writing. In addition to some interesting podcasts I found this informing article: Documentation Usability: A Few Things I’ve Learned from Watching Users. The author has some really interesting suggestions how to improve documentation for applications. In particular he claims that the user manual might not be the best type of documentation for a user. I definitely have to read more on his website. Maybe I can implement some of the ideas in Timeline.

Increasing exposure

In Timeline on August 30, 2009 at 1:44 PM

A few days ago I decided to try SourceForge’s Help Wanted feature. It allows projects to “advertise open positions to potential volunteers.” I wrote that we needed help translating our application and returned to what I was doing not expecting the advertisement to have any big effect. I was therefore surprised to be contacted by three people the next day, all showing interest in translating. Thanks SourceForge for this feature.

This was the first time I actively tried to involve others in the project. After the 0.4.0 release I will also register the project on freshmeat to increase the chance that people find out about it. I believe we are now ready for more exposure.

The Timeline Project

In Timeline on August 28, 2009 at 1:49 PM

In October 2008 I started the free software project The Timeline Project (homepage). I did not know what it would be like; I was not even convinced that the end result would be useful. I was sure of only one thing: I would learn a lot and have fun programming along the way.

In posts in this category I will record thoughts on running and developing this small free software project.