Coding Clarity

Problem. Bugs happen. The common solution to this problem is to fix the bug and release a patch. Version 1.0 has bugs, version 1.0.1 fixes those bugs.

Inevitably at some point in time you will need to put together a list of all of the changes in a release. For me, this needs to go into a format we can post on our wiki. This process can be tedious if it is a manual process. There are a few approaches to handling this. You can go against the bug tracking repository and look for what bugs were fixed for this release. This will tell you everything that should have changed. I say ’should have’ here because you cannot know for sure if the information is 100% accurate.

The other option is to go to the version control repository for information on what has change. This is the authoritative source of what has changed but often contains more information than what you would want in a change-log.

In my previous post on version control I mentioned that we have best practices around format for commit messages. All bugs start with the words “Bug

I wrote a simple groovy script that generates this change-log for me. It uses the subversion command line interface. The starting point is using the 'svn log' command. This command generates a change-log. Here are the options used to this command:

• The ‘–xml’ option is used to format the output as XML. This allows groovy to break it down easily.
• The ‘-g’ option is used which shows log messages from other revisions that were merged onto this branch. Let’s say you have 50 bugs that are merged onto the bug fix branch all at once. This would create a single revision on the branch. Using this option includes all 50 comments from their original commit on the trunk. This detail we want in the change-log. This gives nested entries though so the code has to handle that case.
• The ‘-r’ option is used to specify the revision range to use. In this case for a branch, we want from the previous release revision number to the current (or HEAD). For this example, let’s assume the 1.0 branch was at revision 1528.

The command to run then becomes:

svn log -r HEAD:1528 -g --xml

The next step that needs to be done is to take this XML and turn it into a change-log. I plan to use this as a comment into a wiki so I prefix the lines with ‘*’ so they will appear as a bulleted list in trac. It also puts the revision number at the end of the line in brackets. The output should look like this:

 * Bug 123: Fixed some bug (1554)
 * Bug 126: Some other issue (1588)
 * Bug 322: Fixed the thing (1600)

To generate this changelog, I wrote a groovy script. It uses the svn command to generate the changelog and uses Groovy’s XML Parsing to break it up and format it. The path to the working directory and revision number would change from release to release but the rest of the code is reusable.

def handleEntry
handleEntry = {entry->
    def message = entry.msg.text()
    if (message.size() >= 3 && message[0..2].equalsIgnoreCase("bug")) {
        println " * $message (${entry.@revision})"
    }
    entry.logentry.each(handleEntry)
}

def proc = "svn log -r HEAD:1528 -g --xml".execute(null, new File("/path/to/working/directory"))
new XmlParser().parseText(proc.text).logentry.each(handleEntry)

Two of the most useful tools to a developer outside of their development environment are version control and bug tracking systems. Version control allows tracking of changes to the product and allows for branching and merging. Bug tracking systems allow for tracking issues with the product whether they be bugs or enhancements.

Even though these tools are often separate products, they have a major commonality which is the code you are working with. Often times you want to be able to see for any given bug number, what code was changed for that bug. Also, for a change in the code (in version control) you want to see if it was associated with a particular issue in the bug tracking software.

At the company I work for we use Subversion for version control and Bugzilla for bug tracking. We have some best practices around these tools to make things easier.

Version Control and Bug Tracking Best Practices

When resolving issues in the bug tracking database, our team always puts in the build number of the build that contains the fix. This way a person who is looking at the bug can know if the build they have contains the fix. Anytime our team fixes a bug we put in a comment that looks like this:

Build Fixed: 1.0.1.12354

The last number is the revision number in Subversion.

When we commit code changes to Subversion, we also include the bug number for the bug being fixed. Our commit messages always appear in this format:

Bug 1234: Fixed this bug

Subversion Tooling

Recently I came across a neat feature in Subversion that allows you to link it to a bug tracking system. Basically this allows clicking on the bug number in the subversion history view to take you directly to the bug number in the bug tracking software.

Enabling this feature is fairly simple to do and involves setting 2 properties in the subversion repository. These properties need to be set on the root folder in subversion that you would use to checkout your project from. It automatically is available for everything in that tree but you need to checkout from this root for it to work. These are the two properties that need to be set.

• bugtraq:logregex – This defines a regular expression to ‘match’ bug numbers in subversion comments. For the pattern I listed above, we are using: [Bb][Uu][Gg] (\d+)
• bugtraq:url – This defines a URL to go to when the user clicks on a bug number. The browser is launched when the number is clicked on and takes you to this URL replacing the BUGID parameter. For our bugzilla repository we are using: https://some.server.somewhere.localhost/show_bug.cgi?id=%BUGID%

The following steps walk through this process of how to set this up using Tortoise SVN:

• On the root folder of your subversion working copy, right click on the folder and click TortoiseSVN -> Properties.

  

• Add each property listed above as new properties to the list.

  

I’ve decided to use Apache Maven for building the code for my new project. So far I have had a love-hate relationship with Maven. If you don’t know what maven is, the folks over at Apache say Maven is …

“… a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project’s build, reporting and documentation from a central piece of information.”

Unfortunately that definition is about as vague as you can get so I will explain what Maven gives me and my project. This also happens to be the list of what I love about Maven:

• Maven enforces a standardized project structure to all modules in a project.
• Maven handles dependencies between libraries.
• Maven builds all of my code and creates a distribution package.

Essentially by using Maven, I can get all of these things without having to write and maintain ant scripts to do most of the work for me. Maven is not without its problems though.

• Often times the number of lines of XML you need to write ends up to be just as complicated and long as an ant script to do the same thing.
• I’ve found a lot of bugs particularly with the assembly module. It seems to include dependencies of modules that are set with the “compile” or “test” scope only.
• The Groovy building plugin for maven does not yet work for Groovy 1.5.x.

I still think using maven was a good choice for my project. It may have some qwerks but I think that I am further ahead than if I had to build everything from scratch.

Using Maven to Generate a Build Number

Earlier I metioned that I use the subversion revision number as a build number. This is actually quite easy to do from Maven. The following plugin descriptor provides you access to the subversion revision number using the ${scm.revision} property.

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-scm-plugin</artifactId>
        <executions>
          <execution>
            <id>getting-scm.revision</id>
            <phase>validate</phase>
            <goals>
              <goal>update</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

Once you have access to the revision number, you can construct a build number using the product version and the revision number. I have added this build number to the Implementation-Version property of the jar manifest. The following plugin definition does this for me:

      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <archive>
            <manifestEntries>
              <Implementation-Version>${this.version}.${scm.revision}</Implementation-Version>
            </manifestEntries>
          </archive>
        </configuration>
      </plugin>

The resulting manifest in the jar looks something like this:

Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Created-By: Apache Maven
Built-By: cdail
Build-Jdk: 1.6.0_03
Implementation-Version: 1.0-SNAPSHOT.93

From Java code, this build number can be easily retrieved. The following code retrieves the Implementation-Version from the manifest:

Package p = getClass().getPackage();
String version = p.getImplementationVersion();

The result is quite elegant but it takes a bit of work to get things into place. Like with many other things to do with Maven, it takes a while to figure out how to do what you want and you need to write a bunch of XML. Once that was done, everything fell into place. It is hard to say at this point if this is better or worse than the chunk of ant script I used to use to perform the same function.

I had a Mathematics teacher in High School who used to get very excited over factoring problems where you could simplify expressions by canceling out terms. He used to say it was just like “taking out the garbage”. Taking out the garbage was not usually a fun task but it is surprisingly satisfying to get rid of stuff that is not necessary and is just clutter. I run into this same sort of thing when developing software. I just love to “take out the garbage”.

Version Control software is essential to any project, no matter how small (That in itself is a topic for another day). Version Control software gives you the ability to take out the garbage all of the time without having to worry about losing something that is important. You can always go back to old versions of a file if you need them at a later point in time.

Delete Unused Classes

Often when you are refactoring a component or adding something you end up with a Class that was used before that is no longer relevant. Delete it. Remember that you can always get it back later if you need it again through your Version Control system. It does not matter how ‘useful’ this code was, how ‘nice’ it looks, how ‘cool’ it is. It may have been a useful utility that you might need again. You have to resist these urges to keep it around. Unless you know for a fact that you will use it again, you should get rid of it. It is not gone forever and you can get it back if you need it. This will help reduce the complexity of your code and consequently the readability.

Delete Unused Code, Don’t Comment It Out

I see a lot of developers who take a piece of code that is no longer used and comment out the entire section. Resist the urge to keep it inside the code. You can always get the code back through version control, so why do you want to keep a long comment block somewhere where it needs to be maintained? Another danger to this is that if you do want to use this code later on, you will likely end up removing comments around code that no longer compiles. Things change and this once working code may no longer work after you uncomment it.

The follow code is a good example of this. The line that was commented called a function that takes 2 parameters. Notice that the current version of the function takes only one. Code blocks that are commented out are not compiled so the code is not kept up to date with the rest of the code.

// We don’t need to do this anymore
// variable = someFunction(a, b)

someFunction(a) {
…
}

It is simply better to just delete the code block. If you need it at some point in time later, the version control software can resurrect your lost code.

Bug #12324 Add a heading here
Bug reference numbers are not necessary

I have seen lots of code with comments around a changed block indicating the change was for a particular bug. Before long, the code has a mess of comments all over the place indicating bugs that were fixed and where. This is another case where version control software can eliminate comments that unnecessarily clutter your code. This one does require a bit more discipline though.

Always indicate the bug number being fixed and a small when checking in code into Version Control. For example, you could add a comment like “Bug 12324: Added heading to section”. Then when you look through the Version Control log, you can easily see where changes were made and what they were made for.

If you are looking at a particular line of code and you need to know where it came from and why, you can use the “blame” feature. That will give you the person who last changed the line of code you are looking at along with the comment (which should include the bug number and fix description). For more information on this feature of version control systems, check out the “Who wrote this Crap?” (http://www.codinghorror.com/blog/archives/000992.html) article on Coding Horror.

Taking Out the Garbage

So next time you are confronted with “stuff” that is not longer used. Delete it and let your version control do the work of remembering it. This will keep your code much cleaner and easier to read. It is just like taking out the garbage.