Recording Project Progression

When you develop an application you start small and successively build more complex structures. Wouldn’t it be nice if you could record the whole process and study and repeat each successive step that you make? It would be very valuable for teaching purposes, but also for remembering what and how you did it. It is not unusual to go back to your own code several months after you’ve created it, and try to understand it. But if you don’t have the intermediate steps you might have difficulty to recreate your thought processes and understand how you did it, and what the difficulties were involved. If anyone has any ideas of how this could be realized I would like to hear it.

One idea is to use preprocessor directives. There are three of them that matter
You can make a file called perhaps Version.h which you can include in every header of your other classes.

#include "Version.h"

In Version.h you can write a single line, for instance

#define CODE_VERSION 3

Then you can use the #if directive to keep track of different versions, something like:

[code]#if (CODE_VERSION <= 2)

  • (void)drawRect:(NSRect)dirtyRect
    // one version of drawRect

#elif (CODE_VERSION == 3)

  • (void)drawRect:(NSRect)dirtyRect
    // another version of drawRect


  • (void)drawRect:(NSRect)dirtyRect
    // still another version of drawRect
    #endif [/code]

In this way you can at a glance see what differs between the different versions and how the project has evolved.

Revision control software. Try subversion or git, or any other software that lets you easily get back to a series of files as they were in the past.

I’m most familiar with subversion (SVN) so that’s what I’d use. The principal is that you start with an empty project or template and add that to your repository. Then as you add & modify files, you check in your changes, noting what you did and why. You can also create “tags” as you go to mark milestones (version 0.2.3b, or “first version that saves data”, or “code on 2010-06-21”).

To read up on subversion, and get a brief primer on revision control software, you can read the book at

Thanks for the tip Robert, I briefly looked up Subversion and it says

I do my development myself and have no need to coordinate my code with other people, which Subversion helps you do. Also I do not have a Mac OS X Server, just a plan old Mac, and I would not want to install Apache on it, if I can avoid it. I would rather not mess with Unix commands, if that is required. Maybe I’ve missed something but it seems a little complicated, for something very simple that I need.

I’ve been using Subversion for at least 4 years, and have never collaborated with other developers on a project. While it’s feature set is definitely geared toward that goal, you can use a small sub-set of the commands to accomplish check in, check-out, diff between any two versions, tagging, and reverting to old versions. As for installing Apache, that’s only if you want to run a server that’s accessible to other people over a network/the web. You already have an apache server installed anyway (comes with Mac os X), and there are better/prettier clients that you can install that takes the drudgery out of the installation process. Do a search for those to see if they’ll install a “local” server to handle the repository.

If you want to record the history of progress on any given programming process, subversion (or the more complex revision control software packages out there) is the tool for you. If you still think it’s too much, and you only want to look at one or a tiny number of files as they grow, individually, you might look at managing "diff"s of each file, but that’s a lot of work in my mind.

If you don’t mind someone else running the software, Git is pretty nice! While these things were initially designed to help groups of people work together, I think they still have a role in single-person development. Not only does it allow a Time Machine style record of everything that has changed, it can let you take experimental courses to see how an idea plays out, over dozens of files, and if it doesn’t work out—you can return to the main trunk. If it does, you can fold the fork into the trunk. That is more difficult to do with a single-fork mechanism like Time Machine.

It is possible to do these things without tools, but they make managing complicated diversions much easier, and safer.

But another tool for examining how you worked is to employ a test driven workflow. If you have tests all over the place for everything you ever did, then it not only works as a huge, custom-coded debugging network, but as a roadmap for how things got the way they did. It also makes going back and tweaking things easier, because you can track precisely where they break in the test network.

But TDD is a whole 'nother topic!

I’ve looked up TDD (which seems a very interesting method) on Cocoa and found an interesting article at. … ken-tests/

If what the articles says is true, then it seems that TDD is not mature in Cocoa and that trying to use it will waste more time than it saves.

I’ve looked briefly at the book you recommended and it seems to have been very well written. Thanks for the link.

Source code management is a fundamental practice that is as important for the single developer working in isolation as it is for the large corporation. Current tools like CVS and SVN do not require any server, but can be used in a server context for distributed development. There are numerous SVN and CVS clients available. Most IDE such as Aptana, XCode, Komodo, Eclipse, Visual Studio, all have direct integration to SVN/CVS eliminating the need for a separate client.

SVN is included in OSX. It is extremely portable. Repositories can be moved by simply dragging them around. There really is no reason not to use it.

The method you outline above has several very large disadvantages. The largest is the unneeded complication of source by retaining unneeded code segments that should be removed. The best plan here is to use the right tool for the job.

Preach it Jaysen!

Really? The client & server are pre-installed on OSX?

I am running 10.5 and yes. To run a full blown SVN repository (server) there is some config that needs done, but you can do a local repo with nothing more than some basic setup with any client tool (or command line).

Edit: I do have XCode installed.

As I explained in my first post I want to keep the time history of my code for teaching purposes. So the old code is not unneeded at all, it is the very point that I DO want to keep it. Even though SVN can be good for your own development purposes I do not see how it can be used in a teaching situation. Suppose you write a book and in the book you go through 45 different versions of a certain project, carefully adding one feature after another. You want your reader to follow along and you want to provide him with source code of all the different versions. What do you do? Here are some alternatives:

  1. You send him 45 different projects, each differing a hair from the previous one. To see the changes he must compare two different projects at the same time.
  2. You send him one project with the different versions separated by preprocessor directives. He can see the changes by looking in one project.
  3. You require that he learns SVN and you send him your SVN repository and instructions how to make use of it.

For the teaching situation above, it seems to me that alternative 2 is best, but I can change my mind if somebody can show some convincing advantages of some alternative method.

You want alternative 3.

Using source code management is a fundamental component of development. The underlying skill is a prerequisite to the desired activity. Considering that almost all SVN access would be via a client application which is more than likely embedded in the IDE there is little additional teaching that needs to be done.

If you look at books on programming, especially ones that develop a project from feature to feature, none of them use historical trails in examples. What they show is a “before and after” not a historic inclusive. Your method seems to be counter to the norm.

I think if you take an hour and look at how SVN works using real files you will see that using a SCM solution like SVN is the proper way to go.

I’m sorry if I expressed something unclear, causing misunderstanding, but what I mean by time history is exactly “before and after”, nothing less nothing more. What I have seen in books for instance in Hillegass is that he uses different versions differing by a slight feature. For instance he calls versions KVCFun_A, KVCFun_Final, RaiseMan, RaiseMan_A, RaiseMan_B, RaiseMan Controller, and so on. He uses small projects. I think the biggest one is RaiseMan where he goes through 9 different versions and provides 9 different projects. In a little more advanced project that I had in mind I guess I could go through 45 different versions if I keep the same detail as Hillegass.

In your post you are advocating alternative 3. But that alternative was

I hope you don’t mean that, because many readers would be put off by such a requirement. Hillegass for instance does not require that the reader knows SVN. Neither does Kochan.

But maybe you are just advocating that I use SVN internally, but that I later package 45 different versions a la Hillegass that I give to my readers. In that case, it is not alternative 3 you are advocating but, but alternative 1. What matters to me is not so much what I use internally to produce my code, but what kind of source code the readers get and what makes their learning experience as simple as possible.

I would provide a 1 chapter primer on SVN as related to your course work. Then I would include the SVN repository on your distribution media. SVN repos are very portable.

This is exactly how we distribute examples for training.

Thank you Jaysen. Since you are using it, it shows that it is a viable way, so I will look into it and make a comparison.

Poking around on the Net looking for SVN, I stumbled on what seems a GUI client for subversion. It is an app called Versions 1.0.9, costs 39 Euros, and was a Apple Design Awards 2009 Winner. Here’s what they say at … sions.html

There is also a demo at youtube, see
Has anyone experience with this app?

Neither Kochan nor Hillegass are teaching overarching strategies in the two books I’ve read of theirs, though. They are teaching languages and environments. Hillegass in particular, points out in his preface that the user should already be somewhat familiar with C before they tackle the book, if they are not already familiar with Objective-C. So I don’t think either of these authors omitting programmings practices from their books is a good indicator over whether these practices should not be done.

Like Jaysen, I think versioning systems should be taught to new programmers as a fundamental aspect of learning to program, just as fundamental as learning the languages. Whether or not they use that knowledge is up to them of course, but even in a single-person environment, having a safety network and complex detail management system of that kind can save a lot of time and grief.

Definitely do agree on TDD being poorly support in XCode proper. Coming from a Ruby background, which is probably the poster-child for good base-system support of TDD, XCode is a mess. You have to build a unit test bundle, and muck around with alternate targets and dependencies. You almost need a test network to test the test network. Ha. I’ve installed it, but haven’t started using it yet: however I’ve heard good things about Google’s test environment plug-in for XCode. Google’s solution aside, there are other third-party frameworks that provide better testing that Apple’s system.

If you are just starting out with SVN, take a look at ZigVersion. Pretty much unsupported, but the interface is nice and a “personal” license is free.

My personal preference is that you learn at the lower levels first. So for SVN I would suggest using the command line tools a few times before going straight to a GUI.

Also I would highly recommend a multi-platform IDE with SVN integration. Since I work in PHP, perl, Java, and C variants I prefer Aptana/Eclipse. If I were developing straight Mac, I would fight with XCode for a while before looking for a better IDE.

That is what I would do. More realistically that is what I do.

I’ve looked briefly at SVN and here are my comments. SVN is a wonderful concept but there is a dilemma.

In order to keep track of your revisions you need to learn SVN. In order to get full power of SVN you need to use command line. In order to use the command line you need to learn Unix shell. So unless you already know Unix shell, you are in a learners dilemma, which says that in order to learn anything, you must learn something else first.

One way to circumvent the above is to use a GUI like VERSIONS. However it doesn’t give you the full power of command line SVN. In my case that would maybe be OK, but I can’t ask my readers to invest 39 Euros for a tool, that they may not like. The other alternative is to force them to learn both SVN and Unix shell, and that is does not seem so palatable either.

It seems to me to be a Mac developer you need to learn

  1. Unix shell (maybe also Python or Ruby in order to write powerful scripts)
  2. C
  3. Objective C
  4. Xcode IDE
  5. Cocoa APIs
    If you’re into games you need to dig into stuff which is not object oriented
  6. Quartz (and for speed OpenGL and also for 3D)
    If you’re into web stuff you need to dig into
  7. bla bla
    And so on. I’ve been little frustrated when people say that Mac development is easy, but when you start to dig into it, it turns out to be …


IDE with integrated SVN will provide [size=125]what you need[/size] to get this done. Using the “full power” of SVN is not needed. That simple. Use the parts of the tool that you need. Ignore the rest. Kind of like the claw on the back of my hammer I don’t use it. I have a better way to get the nails out. I still use the hammer to pound the nails in though.