Malcolm Davis's Blog

Programming Archives

It depends

In Anti-Pattern - The Swiss Army Effect, John Reynolds expresses concern of the expansion and growth of Java technology, and the technology overlap that is occurring. For instances where does one go for database CRUD operations? JDBC, JDO, CMP? Web development can be just as frustrating. Web development products include JSF, Velocity, Struts, Tapestry, and Jetspeed for starters. The large selection provides grief to many.

The hammer
"If the only tool you have is a hammer, you tend to see every problem as a nail." - Abraham Maslow

Microsoft's claim to fame is their one homogenous, well-integrated, do it all environment. Even though Microsoft VisualStudio falls way short of free tools like Eclipse, and the .NET architecture is lacking features like an Object/Relational Mapper (ORM), the developers don't have all those decisions to make, they just make what they have work. Is it choices that breed discontentment?

The hammer mindset is understandable. Getting a solid grasp around just one of the tools is difficult. Both developers and customers try to learn one technology and apply it to all problems. Trying to look at the market place and second-guess the future is equally dreadful.

It depends
The experienced engineer seems indecisive. Whenever asked a question, the engineer simply replays with 'it depends'. What is the web site developer trying to accomplish? If it's a static content site, maybe Cocoon is the answer. Is it's a portal site, maybe Jetspeed. Perhaps Struts if the site requires dynamic web forms. Does the customer allow open source? Has the customer already invested in a specific technology? Who are the other developers on the team? What is the time frame of the project?

Knowing the basics of solid development far outweighs which package/technology/tool used. Tools & technology change, concepts and practices just adapt to the changes.

Final thought: Regardless of the profession, doctor, lawyer, or engineer, the focus is on the 'principles' and not the 'tools'. Being a great doctor does not change based on new drugs or procedures. Great doctors work to understand the unique needs of the patient by doing such things as analyzing symptoms, understanding the patient history, and simply listening.

Class variable names

In "Code Complete" section 9.4 informal naming conventions, Steve McConnell describes the use of module variable 'm_'. Since reading this in 1994, I have used the 'm_' convention in C programs, then C++. I've seen 'm_' used in MFC, and in coding standards for the commercial software companies.

Even though Sun does not explicitly define class variable declaration in the coding standards, much of Sun's code aligns parameter names to an existing field with the same name. Much of Sun's code uses 'this.' to set member variables.

public void setName(String name) {
    this.name = name;
}

I asked Steve McConnell his opinion about 'm_' versus 'this.'. The following is his response:
...
"In general, I'm not crazy about differentiating parameters from member variables solely through use of "this.". I would rather see unique names for all variables. I think you're inviting problems and making the code harder to figure out if you name everything exactly the same. I'm not wedded to the "m_" prefix specifically, but I'd like to see the member names and parameter names be unique through some technique or other."
...

Some people use the underscore '_' to determine a variable's scope, such as Docman at SourceForge. Hence, the above sample would be:

public void setName(String name) {
    _name = name;
}

I've also know people to use 'p_' for differentiating parameters, as shown to the following sample:

public void setName(String p_name) {
    m_name = p_name;
}

C# has a different twist by providing a 'property' feature: (note the implied 'value')

public string Name {
    get {  return name;  }
    set {  name = value; }
}

Even though the C# 'property' feature looks good on paper, in practice the feature is widely misused.

The software language scene will change a great deal over the next few years with the arrival of meta information, aspect oriented programming, code generation integration, and new programming features like C# properties. However, I think at this point, it is still important to differentiate the scope of variables. Even though it looks Hungarian in nature, the focus of Hungarian notation is to identify the type of a variable, not the scope. The issue with Hungarian is that the classical types did not fall into the Object-Oriented world, and types very often change.

The Humble Programmer

I've looked for the Humble Programmer sometime ago, and all I could find was a used copy on Amazon. You can now download a PDF copy from http://www.cs.utexas.edu/users/EWD/ewd03xx/EWD340.PDF

Over the last 30 years, many of the themes Dikjkstra talked about have been re-communicated over and over again. For instance, "The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague.."

In Writing Solid Code, Steve Maguire says "Write code for the 'average' programmer".

toString() - any format recommendation?

Many times the toString() format is dependent on how the developer wants to see the state. I've seen formats to accommodate Swing, console, the debugger, and log files. To help format Value/Transfer objects consistently, I use a utility method that employs reflections.

Use:
public String toString() {
    return ToString.format(this);
}

Sample output:  
[com.company.business.Address: Key=0, State=AL, Country=USA, City=Helena, Street=1313 MockingBird Lane, Zip=35000]

To mitigate issues with logging, I avoid carriage return and line feeds. To help differentiate embedded objects, the objects are enclosed with '[' and ']'.

[com....Customer: …, Address=[com....Address:…], Phone=[com....Phone:…],…,…] 
(where com... is short for the entire package path, com.companyname.business.etc..)

Any thoughts?

Simian

A certain degree of copy and pasting occurs with every development project. The problem is many times overlooked, or missed during code inspection. Simian helps stop some of this monkey business by searching through text files (like Java and C#) and identifying duplications.

To do some testing, I ran Simian against a recent project. After running through 250K+ lines of code (LOC) in 20 seconds, Simian had found 47129 duplicate lines.

I guess you can expect some duplication with 250K+ LOC written by 10 developers in 10 months. Further investigation discovered many of the code duplications were in auto-generated sections. [Of course this makes you wonder about the code generation process]. Additionally, some of the dups found were over common coding variables usages in routines.

Simian seems to look for exact copies and not similarities. A more meaningful tool would be something that found algorithm 'similarities' in code. A more common problem with copy and pasting is when a developer copies a section code, then makes a minor mod. In the following example, the developer intended to have a common display format of the form of identifier + description.

Class Member
    public String displayText() {
        return "[ " + memberId + " ] " + name;
    }

Class Branch
    public String displayText () {
        return "[ " + branchId + " ] " + description;
    }

The developer copied the code and made a small mod. [Yes, this is a real world example.]

The concept is valid, and Simian does find many copy & paste problems. Simian helps automate the process by providing an Ant tag. Additionally there are plugins for Checkstyle and Eclipse. [I was able to get Simian to work in both 2.1 and 3.x of Eclipse.] Simian can be found at http://www.redhillconsulting.com.au/products/simian. Unfortunately, Simian is neither Open Source, nor free for commercial use. However, it is free for Open Source projects, and inexpensive to purchase for commercial.

Clear the CLASSPATH

One developer, 2 modifications
A developer has made 2 modifications, one to a client class, and a second to component classes. The client and component classes are packaged separately, but deployed together. When the developer tries to run the application, a "NoSuchMethodError" exception is thrown.

The "NoSuchMethodError" problem is a common one seen by developers new to Java. The exception is difficult to track down. Everything compiles and works on the developers box, but the error occurs when the application is deployed. Generally, "NoSuchMethodError" is caused with when the method signature of a class has changed. So why is the problem only showing up when the application is deployed? The CLASSPATH variable is the first place I look.

When the virtual machine starts up, the VM searches for and loads classes in the following order:

• Bootstrap classes - Classes that comprise the Java platform.
• Extension classes - Classes that use the Java Extension mechanism and are located in the extensions directory.
• User classes - These are classes located by the -classpath option on the command line (the preferred method) or by using the CLASSPATH environment variable.

The preferred method
The preferred method is to use the application -classpath and NOT the global environment CLASSPATH variable.

• The JVM I've worked with, if a class shows up multiple times in the classpath, the first class is used and the second occurrence is ignored. Therefore, it cannot be expected to override the default global class with an updated jar on the java command line.
• Most likely a variety of applications will be running on a server. Different apps may/will require different versions of the same component. With the proliferation of open source, it is not uncommon to see multiple versions of Log4j or ORO on a box. Requiring all the Java applications to use a single version Log4j will eventually lead to problems.
• Pollution of the JVM space. A simple application may not require any supporting jars, but placing classes in the global classpath forces the JVM to deal with a support package each time an application is started. [Yes, the JVM has gotten much smarter about this problem, but I wouldn't expect every JVM to work the same, or handle the problem 100% perfectly.]

The nightmare begins
In IT environments with servers configured by an administrator, things get crazy. Some admins place common JARS in the java\lib directory; others have complex login scripts that dynamically change the environmental variables. Understanding the classpath in these settings becomes a nightmare. It only gets worse with different versions of J2EE environments. Some J2EE engines have started to use more and more open source components. If an application and a J2EE container are using the same open source component, with a different method signature, BOOM. Even if the application is J2EE compliant, that doesn’t necessarily mean the app will run correctly on all application servers.

NoSuchMethodError
At least the "NoSuchMethodError" indicates that there is a problem, and gives a clue of where to look. Many times the method has changed, but the method signature has not. These problems are much more difficult to track down. Clearing the CLASSPATH will require a little more work on initial configuration of each application, but it will save a host of problems.

RI the application

What is RI
Many developers first introduction into J2EE is in the form of JSP & Servlets. Using JSP & Servlets requires the services of a servlet container, and one of the most commonly used is Tomcat. However, Tomcat is more than an open source servlet container, Tomcat is also the Servlets and JavaServer Pages reference implementation (RI).

Tomcat demonstrates one of the core strengths of Sun’s work with Java, specifications and reference implementations.

Why RI
Initially, Tomcat did not promote itself as a production quality container. Industrial strength containers came in the form of JRun, BEA, IPlanet and many others. Tomcat provided several benefits to the developer:

• Because it was missing all the bells and whistles of the commercial counterparts, it was lightweight, fast, and easy to setup.
• A low cost entry into learning Java web technology.
• A tool to insure applications meet the Servlet/JSP specs. Many vendors provide extensions to the container. Using the vendor specific extensions in application development can hinder porting applications to other containers, or even newer versions of a vendor’s container.

Application portability
Everybody seems big on applications portability until it reaches Web development, then they have no problem being hooked into a single vendor. The mindset I have observed over and over again is: ‘we are not going to switch vendors’. The implied ‘never’ plagues organizations of all shapes and sizes. I’ve seen a single organization switch vendors 3 times over 4 years, each time saying they are migrating to a single vendor.

Fusing with a single vendor is worse then selecting a single OS, IDE or anything for that matter, and saying we will never change. Change is inevitable due to business needs, technology, or vendor offerings. The best way to fight change is to stay application vendor neutral.

The EJB container
The lonely cousin to the Tomcat is the J2EE platform RI. The J2EE RI is provided by Sun and can be found at http://java.sun.com/j2ee/. The J2EE RI contains all the things that Tomcat does not, like EJBs and JMS. The J2EE RI is:

• Lightweight and easy to setup.
• A low cost entry into learning J2EE technology.
• A tool to insure J2EE applications meet the specs.

Nevertheless, for several reasons developers have not used J2EE RI.

• Previous to J2EE 1.4 releases, the RI was only for development and not deployment.
• Many major IDE did not support the J2EE RI. Only recent versions of JBuilder Enterprise support the RI, and MyEclipse still does not support the RI. [However, Genuitec does plan to extend the MyEclipse Enterprise Workbench to support the J2EE 1.4 RI.]
• Organizational attitudes. The Java mindset is having a difficult time penetrating the corporate world due to things like the fear of open source, lack of understanding of RI, and the stance on using single vendor implementations.
• Not all vendor implementations are RI compliant. Even if the application were developed with the RI, it might not execute correctly in the vendors application server. For example, frameworks like Struts had problems deploying to particular application servers that were supposedly J2EE certified.

Included in the build
Not all is lost, if the RI cannot be included in your organizations development process, it can be included in the build by using the Application Verification Kit (AVK). The kit can be found at http://java.sun.com/j2ee/avk/. Among other things, the kit contains the ability to search source for items that are not J2EE compliant. Ant extensions are provided that help find things during the build process. I doubt AVK will catch everything or solve all RI problem in a organization, but it’s a place to start.

Sun is working to solve the usage problem with J2EE RI by allowing it to be used in production, and working with tool vendors to have it included in product lines. Maybe someday I will see companies using the J2EE RI as the standard for development as many have done with Tomcat.

Specification insight

There are many ways of getting started on a new piece of Java Technology. Developers do searches on Google, check their favorite online publication, go to Amazon for books, view tutorials on java.sun.com, etc… But, one source that is frequently overlooked is the specifications.

When I started JSP and Servlet development about 4 years ago, I thought it was Sun’s version of Microsoft ASP technology. Then a friend of mine, Joe Wortmann, handed me a copy of the JSP and Servlet specs. Joe explained this importance of starting at the specs. I like to hack and experiment, I thought the specs were for wimps, but I gave it a try anyway.

Reasons to start with specs
After spending some time with the docs, I found JSP & Servlet was not just another version of Microsoft technology. Additionally, the specs gave me insight into the workings of the technology. Specifications explain:

• Mindset: The basic mindset of the technology, what the technology is, and what it is not.
• Features: Characteristic of the technology, for instances “How does Servlet deployment work?”
• Description of the interfaces
• Location of additional resources
• Other related specifications

To the point
Specs get to the point, and avoid the clutter (and slant) of vendor specific documentation and tools. Many times vendor documentation tends to be missing important parts, just cover installation and configuration, or just point out vendors specific extensions to the technology in question. Additionally, many times developers get so hung up on the vendor tools they don’t understand the underlying technology.

Answering questions
Having the specs around help answer questions, and help get projects done the correct way. For instance, a common web project question is: “Can I stick HTML and images into the WEB-INF folder?” To answer the question, I simply refer to the specs: “It is important to note that the WEB-INF node is not part of the public document tree of the application. No file contained in the WEB-INF directory may be served directly to a client.”

Other resources
Specifications are not a replacement for other resources such as books, articles, tutorials and vendor documentation. These other resources provide insight into usage, development, and implementation patterns that help smooth development, deployment and maintenance.

Final note
Some specifications have grown considerable over time. The Servlet specs have grown from 79 pages in version 2.2, to 257 pages in version 2.3, to a whopping 330 pages in 2.4. Don’t let the doc size scare you off. Generally the specifications are provided in multiple formats such as HTML, PDF and PS. I keep a bookmark to copies on my machine.

Whenever I learn a new piece of Java technology, such as JMS, I download the specifications and start reading. The only problem with this approach is that you may get irritated at people that don’t read the specs, or the vendors that do NOT develop products to the specs.

Thanks Joe. :-)

Adapt the Java style for your own

Getting C/C++ developers to adapt new coding conventions can be frustrating to a team lead and other Java developers. Coming from a C/C++ and Microsoft background, my style was somewhat different from Sun's guidelines. I found that I was reformatting code all the time to my own convention. Reluctant to change my ways, and looking for every justification in the world not to, I asked experts for guidance. Then Bruce Eckel gave me some words of advice that are paraphrased as follows:

"..not only has Sun worked it all out (and why re-invent a good wheel), but more importantly because everyone sees the Sun code and becomes used to it -- why add the extra mental cycles necessary to shift gears every time you jump to 'your format.'"

After reading Bruce's comments, I got over my ego, and changed my coding habits. Within a few months, the Sun style had become my native convention and I had successfully re-tooled 10 years of C/C++.

While the changes might seem minor and insignificant, I had a huge increase in productivity due to Java comprehension. [It's interesting how much an ego can get in the way of being a better programmer.]

Sun's Code Conventions for the Java Programming Language can be found at http://java.sun.com/docs/codeconv/

Notes:

• The Java certification exams given by Sun use the code convention. If you plan on becoming certified, adapting to the Java style will help.
• Even though code-reformatting tools exist for every environment, code reviews go much smother if everyone is using the same standard.
• It helps with the understanding of the reference material from books, professional journals, and Java technology specifications.
• Having one global standard helps between hired developers, or developers inside a huge IT organization.

This work is licensed under a Creative Commons License.