Making code reviews easier

Our source trees at work contain quite a few files spread out over many directories.  So reviewing code changes done by other engineers used to present a challenge.  Being handed 10 files to review used to mean manually finding each in the source tree so I could set up my diff tool with the appropriate paths to see what changes had been made to each file.  So I came up with a small bash script to automate the finding of base source files for comparison.

When I receive an e-mail containing source files to review, I copy all the modified source files to a directory called /c/review/new (this directory looks odd because I'm stuck on a Windows machine and run Cygwin to make it easier to use).  Then I cd to the top of a source tree with no changes I keep synched up with our SVN server and I type the name of my script below.  I call it "revcp" for review copy.  It finds and copies files from the current directory into a directory called /c/review/old.  Once that's done, I fire up WinMerge pointing at the old and new directories.

The only thing which can present a problem is that sometimes there are files for review for which there are multiple matches.  Makefiles are a prime example since we have quite a few of them.  The script will find all matches and prompt the user for which file to copy.

Is it perfect?  Not by any stretch of the imagination.  But for a "quick and dirty" tool which only took 15 or 20 minutes to write, it saves me quite a bit of time.  Now I no longer dread the arrival of code review requests.

#!/bin/bash
#
#   revcp (review copy)
#
# Description:
#   Given a single directory containing a group of source files to be
#   reviewed, this script will find matching files from the source tree
#   starting at the current directory for comparison.
#
# One time preparation:
#   1)  Modify NEW_DIR and OLD_DIR environment variables below to specify
#       the directory where you've placed the files to be reviewed and
#       the directory where you'd like the corresponding base files
#       to be copied.
#
# To use:
#   1)  Copy all files to be reviewed into the directory pointed to by the
#       environment variable NEW_DIR set below
#   2)  cd to a directory in your source tree above all files being reviewed
#       such as /c/svnBase/riot/client (where svnBase is the directory where
#       your svn source tree is checked out).
#   3)  Run this shell script under Cygwin or another Unix shell.
#   4)  If duplicate files are found by script the user will be prompted to
#       choose the desired file.  Once chosen, the script will manually copy
#       the selected file to OLD_DIR.
#   5)  Use WinMerge or another diff utility which can diff entire directories
#       to compare the contents of OLD_DIR with NEW_DIR
#

# This directory contains new files to review
NEW_DIR=/c/review/new

# Files found from current path will be copied to this directory
OLD_DIR=/c/review/old

FILES=$NEW_DIR/*

function FindMatchingFile
{
    CurFileName=`basename "$1"`
    NumFiles=`find . -name $CurFileName -print | wc -l`
    if [ $NumFiles -eq 1 ]; then
        echo "Copying $CurFileName"
        find . -name $CurFileName -exec cp {} $OLD_DIR \;
    elif [ $NumFiles -eq 0 ]; then
        echo "File $CurFileName not found... must be new file"
    else
        echo ""
        echo "Found multiple matches for file: $CurFileName"
        echo ""
        MatchingFiles=`find . -name $CurFileName -print`
        i=1
        for m in $MatchingFiles
        do
            echo "$i - $m"
            let "i=i+1"
        done
        echo ""
        echo -n "Enter number of the file to copy or 0 to skip: "
        read FileNum
        if [ $FileNum -eq 0 ]; then
            echo "Skipping $CurFileName"
        elif [ $FileNum -le $NumFiles ]; then
            i=1
            for m in $MatchingFiles
            do
                if [ $i -eq $FileNum ]; then
                    echo "Copying file #$i - $m"
                    cp $m $OLD_DIR
                fi
                let "i=i+1"
            done
        else
            echo "User input too large"
        fi
        echo ""
    fi
}

echo "revcp - copy files for review"
for f in $FILES
do
    FileNameToFind=`basename "$f"`
    FindMatchingFile $FileNameToFind
done

Changing to a sibling directory easily

I deal with multiple source trees on a daily basis.  Occasionally it's handy to switch from a subdirectory in one to the same subdirectory in a different source tree.  So I put together the following set of shell functions (similar to command aliases but they allow greater flexibility in checking parameters) to make this easier.

For example, let's suppose my current directory is ~/src/tree1/subdir1/subdir2/subdir3/ and I want to switch to the same path in the directory ~/src/tree2.  With these bash functions defined, I can type the command "cds tree1 tree2".  If I want to return to the previous directory, I can hit the up arrow key to recall the command, cursor over, and change the "cds" command to "cdsb".

# cd sideways (replaces one portion of current path with new string and changes to that directory)

function    cds

{

    if [ -z "$2" ]                           # Is parameter #1 zero length?

    then

        echo "Usage: cds DirPatternToReplace DirNewPattern"

    else

        NWD=`echo $PWD | sed -e "s/$1/$2/"`

        echo "Changing directory"

        echo "from: $PWD"

        echo "to:   $NWD"

        cd $NWD

    fi

}

# cd sideways back (same as previous command but parameters are reversed to go backwards)

function    cdsb

{

    if [ -z "$2" ]                           # Is parameter #1 zero length?

    then

        echo "Usage: cdsb DirPatternToReplace DirNewPattern"

    else

        NWD=`echo $PWD | sed -e "s/$2/$1/"`

        echo "Changing directory"

        echo "from: $PWD"

        echo "to:   $NWD"

        cd $NWD

    fi

}

Bash history

I've always had a strong preference for using command lines interfaces (AKA CLIs) over GUIs.  I can get tasks accomplished much faster using a Unix bash shell than I can on any GUI.  Plus CLIs lend themselves to greater levels of customization than GUIs do.  If I can customize a user interface, I can adapt it to the way I prefer doing things which makes the CLI even faster to use.

One of the customizations I use in Unix style shell interfaces is to modify how commands are stored in the shell command history.  I prefer the Bash shell (AKA Bourne Again Shell).  If you don't understand the humor in that, a little time on Google can clear it up for you.

The first step I took is to specify a permanent file for my shell history.  This allows multiple shells to share the same command history which frees me from the need to remember which shell I entered a command of interest into so I can recall it.  The following lines in a .bashrc file will set this for me.

# override default history size and file settings
export HISTSIZE=10000
export HISTFILESIZE=20000
export HISTFILE=~/.bash_history

I also need to prevent my history from being wiped out when a shell is closed.

# prevent closing a shell from overwriting history (append instead)
shopt -s histappend

I also find it helpful to store timestamps for each command stored in the history.  This can be useful for shared computers where you may not be the only user entering commands.

# Store timestamp information for each command
export HISTTIMEFORMAT="%m%d %T  "

I also hate seeing duplicate commands in my command history.  One of each is sufficient and any more than that just clutter up the history unnecessarily.

# don't store duplicate commands
export HISTCONTROL=ignoredups:erasedups

And last but not least, I hate to waste space in my command history for short commands.  Typing ls is faster than looking it up in the command history so why waste space that could be storing more complicated commands that are harder to remember?

# ignore certain commonly issued commands
export HISTIGNORE="env;exit;history;ls:ps:pwd"


These lines added to your .bashrc should work on Linux, Cygwin under Windows, or Mac OS X terminal sessions.

Sharing data

These days I split my computing time between a desktop computer at work, a desktop computer at home, a tablet device, and a smartphone.  Frequently I find myself wanting to save data in the form of a bookmark, a link to a web pace, or a note on one of these devices to access later on others.  Fortunately, there are a number of applications which make this easy.  Here are the applications I've picked to do the job.
Dropbox - Installing this application on computers and mobile devices allows effortless sharing of all types of files between devices.  Dropbox gets used by a number of other applications like PlainTest (listed below) to make life easier.
PlainText - Allows easy viewing and/or editing of text files stored on your Dropbox account from your mobile devices.  Only available on iOS devices like iPhone and iPad but you can find similar applications for Android devices.
Xmarks - Makes keeping bookmarks synchronized between browsers on desktop and laptop computers dead simple.
Instapaper - Ideal for those URLs you stumble upon on an application on one device that you want to save for later viewing.  A number of mobile device applications such as Twitter feature integration with Instapaper to simplify the task of saving interesting web pages.

Windows development tools

It's no secret that given my own choice, I'd abandon the use of Windows PCs altogether.  However it's a sad fact of life that many of development tools I need to use at work are commercial Windows based tools.  In order to make using a Windows PC on a daily basis more bearable, I add the following tools.  An unmodified Windows PC is almost unusable to me these days.  I've no idea how anyone can get anything done on an unmodified Windows PC.
All of the following tools are free except VMware.

• 7zip - The best archive utility I've found for Windows.  It handles all the archive formats I need to use like ZIP, RAR, and TGZ.
• Ack - A handy little Perl script similar but superior to Grep which searches only source files.
• ctags - Creates tags files which many editors, including Vim, can use to make source code navigation dramatically easier.
• cygwin - Well worth it for the Unix style shell alone but you can add Windows ports of most Unix tools using this.
• DropBox - Makes sharing files between multiple systems possible.  I take it one step further and have added it to my phone as well so my files are now easily portable.
• FeedReader - I'm faced with periodic downtime at work where I have to wait for software builds, downloads, and tests to complete.  This RSS reader allows me to stay up-to-date on development tools and techniques during these intervals.
• Sumatra PDF reader - Using a less popular PDF reader lowers the chances that you'll fall prey to malware using PDF files as a delivery mechanism.
• Irfanview - Handy for cropping screenshots and other light image file manipulation.
• Pidgin - Our office uses IM to stay in touch.  This is a nice little IM program with support for multiple IM protocols.
• putty - I periodically need to connect to remote systems using telnet or ssh protocols.  This program makes that easy.
• source navigator - Useful for familiarizing yourself with large bodies of source code.
• sysinternals - These utilities proved so handy that Microsoft purchased the company which developed them.
• TeraTerm - A decent terminal emulator.  Handles both telnet and serial port connections but I only use it for its serial capabilities.
• Thunderbird - I use this to monitor my home email account.
• TortoiseSvn - Integrates the Subversion source code control system with Windows Explorer.
• TrueCrypt - A useful program for encrypting files, directories, and disk images.  I use it for some of the files I store on DropBox.
• VMware - I need to run Linux software occasionally.  VMware is the fastest and easiest method I've found of doing this without using a separate PC. 
• Winmerge - This is the best visual tool I know of for displaying differences between files and for merging changes from one file to another.
• winscp - Handy for transferring files between systems using ftp, sftp, or scp protocols.
• Wireshark - The best Ethernet packet sniffer.  It understands lots of protocols and can be extended to understand new ones if necessary.
• Vim - My favorite editor.  It's a Vi clone with modern features like color syntax highlighting and column editing.
• Xvi32 - My favorite hex editor.

Using grep in vim

One of the things I like about Vim (and vi) is the ability to invoke Unix utilities to manipulate text in ways that might be hard or impossible with just the regular editor commands.  It's definitely written with the Unix Philosophy in mind.
One thing I do frequently while debugging problems is to add log messages with a distinct pattern so I can find them easily in the log file.  For purposes of this example, let's assume the pattern I use is XYZ.  If I open the log file in Vim, I can issue the following command to isolate just the lines in the log file which contain XYZ.
^[ggVG!grep XYZ^M
That looks like a pretty complicated command, doesn't it?  But if we examine it piece by piece, it's not really that bad.
At the beginning of the command we've got ^[ which is the escape key.  Look at this ASCII chart if you're not familiar with the caret followed by a letter shorthand for control characters.  I issue the escape key to make sure Vim is in command mode.  While we're talking about control characters, the ^M at the end of the command is shorthand for the carriage return (AKA the Enter key).  That causes the command to be executed.
The ggVG in the command serves to do a visual selection of all the text in the file.  The gg causes the cursor to be placed at the first line of the file.  The V invokes visual marking of text.  And finally, the G causes the cursor to be placed on the final line of the file.  That causes the marked area to contain all the lines of the file.
The real meat of the command is the next part - !grep XYZ.  The exclamation mark pipes the marked text to the external Unix utility which follows which is the grep command.  This particular command line searches for lines which match a pattern of XYZ.
Issuing this command will cause Vim's current data buffer (the full contents of the log file) to be replaced with the output of the external Unix utility which will be just the lines within the log file which contain the pattern XYZ.
That makes it really simple to isolate just the log commands I've added.  Once I'm done, I can either exit Vim without saving or just issue the u command (undo last text manipulation) to leave the log file untouched.

Unix tool: xargs

One of the reasons I like Unix style operating systems so much is the Unix Philosophy.  One of the principles is it's better to include a bunch of small, fast tools which can be combined together to accomplish a variety of tasks than it is to build large special purpose tools which are complicated to use.  One of my favorite of these Unix tools is xargs.  What xargs is good at is taking a bunch of separate lines of input and changing those into arguments for another command.
Perhaps an example will serve to illustrate better than a dry explanation.
Let's imagine we want to find all the source files from the current directory (recursively) which contain the string "stdio.h" and to edit each of those files using vi.  The following line will accomplish that.  Of course in Unix, there are numerous ways to accomplish the same task.  This happens to be my favorite way to perform the task and serves to illustrate the use of xargs nicely.
find . -name "*.c" -print | xargs grep -l "stdio.h" | xargs vi
The first part of the command (that before the first pipe character) is a simple find command.  The only thing worthy of explanation is the quotes around the file pattern.  Unix shells will substitute matches for a wildcard such as this before the find command gets invoked.  If we invoke this long command in a directory containing files which match the pattern *.c, the matches would be substituted on the command line instead of the actual *.c pattern.
The second part of the command is a simple grep command but combined with the xargs command.  This passes the file names output by the find command to be used as arguments to the grep command.  The grep command is looking for files which contain the string "stdio.h", a common c library header file.
The third part of the command simply takes the matching files found by grep and passes them to vi.
This example should work on either Linux or Mac OS X.  It will also work on Windows provided you've installed a Unix environment such as Cygwin.  Cygwin is one of the first things I install on any Windows machine I have to use on more than a casual basis.
Play around with the xargs command to get a feel for what it can do.  It's a handy part of any Unix tech's grab bag of tricks.