Lesson 4 - Code Documentation and Code Versioning

Today we're going to take a look at two very important development practices - Code documentation and Code Versioning.

Documentation

Good documentation is what defines how long a piece of code will last and be reused. A few months from now, and any piece of code that you've written and perfectly understood will seem hazy. It's even more important to document code in a multi-developer environment where more than one developer will be working with the same piece of code.

There's documentation, and then there's over-documentation. Do not go overboard by documenting everything. Document functions - what they do, what parameters they take and what they return. Also document parts of code that aren't very apparent. Perhaps you used a clever trick or an algorithm that isnt very obvious. Document that.

Now that thats over with, I'm going to introduce you to a documentation generator that I like to use. A documentation generator is a tool that, well, generates documentation.

NaturalDocs

I've picked NaturalDocs as our documentation generator. Mostly because I'm comfortable with it and because I like its output format. You'll need to download and install:

1. ActivePerl: Perl for windows.
2. NaturalDocs: The documentation generator.

Modifying code

You must've noticed that the earlier code examples had comments written in an interesting format:

MainWindow.cpp
86 // Function: Run
87 // Creates the window and displays it
88 // Parameters:
89 //   nCmdShow - one of SW_SHOW, SW_HIDE, SW_MAXIMIZE, SW_MINIMIZE
90 // Returns:
91 //   true on success, false otherwise
92 bool MainWindow::Run(int nCmdShow)
93 {

Take a look at Documenting code using Natural Docs to learn more about the syntax. We'll be using this syntax in our examples and it should come naturally to you over time.

Code Versioning using Subversion

[TODO] What is versioning and why is it important

Good practices

• Frequent small commits - Commit frequently. And commit small. Every feature implemented or bug fixed should have a separate commit. This way, if you have to revert a change, you can do that easily.
• Build before committing - Only commit in code that builds! This may not be a big deal when you're the only developer, but it wrecks havoc in a multi-developer environment.
• Diff before committing - Before committing, look at the diff to ensure that you are only committing what you intend to commit and that you haven't changed anything else by accident.
• Sensible comments - Use sensible comments. It really helps down the line when you want to look at the history. Auto-generated changelogs also make sense.

(Borrowed from Fraser Hess)

TortoiseSVN

We are going to use TortoiseSVN because it's the easiest graphical interface to SVN. Go ahead and download TortoiseSVN.

1. Once you've installed TortoiseSVN, create a new folder called win32-tut. For this example, I've used C:\win32-tut
2. Right click this folder and from the drop down menu, select SVN Checkout....
   
3. In the dialog that appears, enter http://win32.googlecode.com/svn as the URL of the repository and hit Ok.
   
4. Hit Ok at this dialog.
   
5. And you've checked out your code!
   

The trunk folder is where we'll do our development. The tags folder is where we'll be tagging a code tree. For the purposes of our tutorial, this is where you'll find different lessons. Most people use tags to mark versions of their software. The branches folder is where you can test stuff without messing up the main trunk. Later, branches can be merged into trunk.

If this sounds confusing, you can read this online book Version Control with Subversion. Then again, we'll be learning these concepts as we go along so you don't have to worry about it.

Next, we'll take a look at internationalization and how you can write applications that can be easily ported to other languages.