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.

A simple sound card usually has line-in, line-out, and mic connections. Line (line level) refers to the strength of the signal. Signals from microphones (or pickups from guitars) are typically weaker than line level and have to be amplified.

The mic input on a sound card probably has some amplifier but I was not able find out exactly how this worked. There also seems to be a difference between “computer microphones” and more advanced microphones. If you use a more advanced microphone you probably plug it into a mixer which has a preamp. The output from the mixer can then be connected to the line-in on the sound card.

Or is the only difference between a “computer microphone” and a more advanced microphone the connector? It feels like a more advanced microphone requires a better preamp than the one that (presumably) sits behind the mic input on sound cards.

Furthermore, the difference between a sound card and an audio interface only seems to be that an audio interface is a more advanced sound card: better AD/DA converters, lower sampling latency, and better sampling rates and bit depth. It is also common for audio interfaces to be external. Maybe because they often provide more inputs and outputs.

If you know anything about how the mic input on regular sound cards works I would be happy to read your comments about it.

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).

Conclusions

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.

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.

For a newbie like me on the Chinese language and Mandarin, remembering the tones of words is very difficult.

One technique that I’ve been using to remember the tones is to associate a person with each tone. Since there are four tones in Mandarin, and my family consists of four people, I have assigned one family member to represent each tone.

For example, the word shū (书) means book and has the first tone. Since the character looks kinda like a sail on a boat, in order to remember this word, I imagine my dad lying on a boat reading a book in the sunshine. My dad always represents the first tone.

This technique works quite well for words that consist of only one character. It does not work so well for words that consist of more than one character. That is because those words have multiple tones (one for each character). When I place my family members in a scene somewhere, it is difficult to remember the order in which the tones come. Maybe if I place me behind my dad, I can remember that the tone that I represent (which is tone three) comes before the first tone, but it gets messy.

Another disadvantage with this technique is that it is difficult to remember the tones for words like mom, dad, and sister if the tones do not correspond to the the ones that I’ve assigned my family members.

For example. The word for mom is mā ma (妈妈). A first tone followed by a neutral tone. But since I have associated the first tone with my dad, I can easily get confused here. But I guess I can learn these exceptions in some other way.

To address the problems of my current technique I have a new idea. I think it might work well, but I have not tried it yet. The basic idea is that you assign a combination of tones to a specific object and then associate that object with a word. For example, the word for Chinese language is Hàn yǔ (汉语). A fourth tone followed by a third tone. Lets say that I associate this tone combination with a panda. Then a panda will always represent this tone combination.

Now I have to learn two associations: that this particular tone combination is represented by a panda (I have to learn this once), and that a panda is related to Chinese language somehow (I have to relate the panda to all words with this tone combination).

For each tone combination I have to come up with an association to an object. This is a bit of work, but once it is done, it is done. For two character words, there should be only 4*4=16 such combinations (and maybe a few others if the fifth neutral tone is included). But I think this will help in the long run.

Another possible positive side of this is that I can maybe remember how a tone combination sounds like by associating a sound with the object associated with the combination.

But I have to experiment a bit more with this to be able to tell if it is useful or not.

• 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.

The view that I woke up to this morning.

jhead -autorot *.JPG

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.

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.