21.3 Windiff and merging code

21.3 Windiff and merging code

In the old days it was customary to use the Unix diff or the DOS fc utilities for this. Now it is more common to use a graphically interfaced tool that comes with your compiler.

Windiff

Microsoft Visual Studio has a utility called Windiff which is pretty easy to use. The tool is still shipped with Visual Studio.NET, but in a default installation, Windiff will normally not be installed, so you may need to run through Visual Studio setup process to select this particular tool to be added onto your machine. It is part of the group of tools added by selecting Visual C++ Tools Win32 Platform SDK in the Setup dialog.

As Windiff is an older program, it may not appear on your Start Programs Microsoft Visual Studio Tools popup menu. If not, you can find it with Windows Explorer or with the Windows Search utility. It will typically reside in the directory C:\Program Files\Microsoft Visual Studio\Common\Tools .

Once you open Windiff , you can ask it to compare two individual files or, which is usually more useful, all the files in two different directories. If you compare directories, Windiff gives you a list of the differing files, and then you can compare these pair by pair. When comparing two files, Windiff has a very nice and unique user interface. It's really a classic of good user interface design. A bar on the left shows a map of the two files with the differing places marked in red and yellow, with red meaning there's extra code in the one file, and yellow meaning there's differing code in the other file. Clicking on the bar jumps you to the location of the file in question. Practice with Windiff a little till you learn how to use it, and don't forget to take a look at the help file.

Once you have found the places where the programs differ , you need to merge the two together. This may work best if both programmers are present “ although if they are prone to arguing (and many programmers are) this may not be such a good idea. Ideally the merge is being done by a person in authority, by the team leader or the chief engineer.

Suppose the two programmers are called Ann and Bob. To merge their files, make notes of where they differ (or leave them open in Windiff ). And to edit the files open them up in Visual Studio as separate windows (you can't edit files within Windiff ). If there are any windows open besides the two files to edit, close them. Select Window New Horizontal Tab Group [or Window Tile Horizontal in Version 6] so you can see both files. Decide which file you want to 'merge into,' Ann's or Bob's. The idea is that you should merge into the file that has the largest amount of new code in it. By talking about the files and/or by exploring them with Windiff , you can decide which has the most new code. Let's say that Ann's file has substantially more differences from the original commonly shared starting-point code than does Bob's. Fix in your mind which file is which in the editor window; you might for instance make sure that the file you are merging into is the upper file on the screen.

Now what you need to do is to scroll through the different files in Windiff , and look at all the places where Bob's code differs from Ann's. Where Bob's code is simply adding on a good feature or fixing something, you want to copy that piece of Bob's code into Ann's code, replacing Ann's code with Bob's. Where Bob's code has the old version which Ann has already changed, you want to just leave Ann's code as it is. If there are some places where Bob and Ann do the same thing in two different ways, you need to try and decide which approach is better. If you can't quickly agree, then use an #ifdef to incorporate both versions. That is, you can use a construction like this:

 #define BOB_WAY  #ifdef BOB_WAY  //Put Bob's code here  #else //not BOB_WAY means Ann's way.  //Put Ann's code here  #endif //End of the Ann's way part of the BOB_WAY switch 

Merging

Once you get the program to start building again, you can try turning the BOB_WAY switch on and off (by commenting it in or out), so that you can tell which *.exe runs better. At that point you would probably want to remove the less-good code, as keeping it in the file will make your file hard to read.

Often there is a temptation to make the merge process 'faster' by not bothering to use a file-comparing utility like Windiff . Can't Bob just tell Ann which pieces of the code he changed and have Ann copy those new pieces in? In practice this rarely works. Usually Bob will forget about some of his minor changes, and when he and Ann go to rebuild the code they will get a lot of error messages. If they're lucky, fixing these errors one by one ends up taking as much time as it would have taken to do the job right with Windiff in the first place. If they're unlucky, there will be some omitted change which doesn't generate a compiler error, but which does create a bug.

Revision control software

If you know that you are going to have to merge your code it's a good idea to try and localize your changes into one part of the document to make it easy to block-copy them. It can also be useful to flag your changes with comments that have your name .

There are advanced software engineering tools such as Microsoft SourceSafe that more or less automate the version control and merging process. Tools such as this are generally known as 'revision control software,' sometimes called RCS for short. An RCS package has several significant features.

The most basic feature of RCS is that it serves as a single centralized repository in which the source code lives. The RCS in fact saves every version of the code that you've given it, so that as well as having your current code in a centralized location, your team has access copies of your earlier builds as well.

RCS treats code files like books in a library. Only one user at a time can 'check out' a given file for editing. Until this user eventually 'checks in' the file, no other user will be able to change the file. You can always get a read-only copy of a file, but only one programmer at a time can check out a file for editing. This helps prevent difficult code-merge situations.

The RCS software normally requires a programmer to make some kind of log entry when he or she checks a file back in. The cumulative log entries help the team track when changes were made.

We're not going to discuss any specific RCS packages in this book, but if every member of your team has access to the same one, you would do well to spend a little time learning how to use it. If you are working in an environment where there is a shared directory (on the web or on a network) then it is definitely worthwhile to use some form of RCS to make it impossible for two people to work on the same file at the same time. As well as Microsoft SourceSafe, there is a well-known shareware Unix-based RCS tool called RCS. It's worth noting that the familiar Macromedia Dreamweaver web-site-building tool can in fact be used as an RCS system. Another option is to use a web-based collaboration tool, of which several exist. For that matter, it wouldn't be too hard to create a web page for your team that effectively acted as your RCS system.

Informally, you can achieve something like the effect of using RCS by being strict about not letting team members work on the same code at the same time. This is really worth doing, as merging code is such a hassle.

Once the group gets a new merged build that works, be sure to clean it, save off an archive copy of the code, make a *.zip of it, and distribute the *.zip to all team members. Without exception , each member of the development team should replace all of his or her source-code files with the new build's source-code files. This is to avoid having to repeatedly fix the same bugs or to merge the same code.