Coding Clarity

Recently I have been working a lot with some people I would call “Old School Developers”. They were brought up in the “glory days” of the pre-internet era of development. I have been tasked with teaching an old dog new tricks. In this case, I am teaching Web Services development using Apache CXF and the Spring Framework to a few C++ developers of 20+ years. These people are really smart and have a good understanding of software development. What they need is a paradigm shift.

When working with these people, I constantly hear concerns about performance. This seems to be the number 1 issue on their mind. They need to be careful that they always achieve the best performance possible no matter how much extra complexity it adds to the code. These constraints even influence the design of the code where fundamental design changes are made for the sake of performance alone.

“We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil.” (Knuth, Donald. Structured Programming with go to Statements, ACM Journal Computing Surveys, Vol 6, No. 4, Dec. 1974. p.268.)

Programmers are notoriously bad at knowing when to optimize code. We end up focusing on the little things when we really should be concerned with reducing more broad performance issues. Is shaving off a few milliseconds a priority when you are dealing with remote web service call over the internet?

My philosophy on software development is to focus on the most important aspects first. As you might have guessed, performance does not make that list. The most important criteria for

• Readability – Write Code that is readable. You or someone else will appreciate it when you have to come back to it at a later point in time.
• Simplicity – Keep it simple. Only build in complexity where required and only to the degree required. You can always refactor it later.
• Say Less – Less code is more. If you can leverage something that exists, do so.

Do not take this the wrong way. I am not trying to say here that performance is not to be considered or that it is not important. I am simply saying that it is not the most important issue. Once you have good readable and simple code, you can go back and optimize it where it needs it. If you start out with performance as a goal, you will never end up with readable and simple code. No one goes back over working and fast code with the intent to make it slower and more readable.

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.

There are many different types of open source software licenses. These range from the Apache License which is very commercial friendly to the GPL License which is not. In a nutshell, the reason the GPL is not friendly towards commercial software is because of the requirement that anything using the GPL code must in tern by provided under the GPL license and also open source. It is understandable that a company creating commercial software would not want their source code to be open.

In many cases the commercial software just wants to use an existing open source library within the product. For this case, the Lesser GPL License (LGPL) exists. This is a lesser form of the GPL that is supposedly commercial friendly. It does not require the source code of the commercial application to be opened nor does it restrict the licensing.

Even though the LGPL was intended for this type of use, many companies are required to stay away from any LGPL libraries. This is because of the following clause in the LGPL:

You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following…

http://www.gnu.org/licenses/lgpl.html

The license clearly indicates that reverse engineering is only permitted for debugging the LGPL licensed library. The problem is really what is the definition of “reverse engineering for debugging”. Many companies do not want to put themselves in a situation where a customer could reverse engineer their code for “debugging” and also manage to get any trade secrets from that process. That type of a legal battle would be difficult and costly to fight. If someone maliciously reverse engineers your code and you bring legal action against them, you do not want to give them any resources they could use as a defense. It is far simpler to avoid the LGPL license all together then you never have to worry about this reverse engineering clause.

That clause was added to protect the integrity of the LGPL library but it has the effect of turning many commercial companyies off the LGPL totally.