MathJax

SyntaxHighlighter

Highlight

Custom CSS

Sunday, September 7, 2008

Arguments against checking in your .project and .classpath files

Update

Note that using Maven is not always a solution to this problem; many projects just don't warrant Maven, plus there are a lot of (working) systems that are already heavily invested in Ant, and would not see a big enough benefit to move to Maven. So, assuming Maven is not being used...

Quite often I see that the .project and .classpath files are checked into the SCM in a project, which can be convenient if all the developers use Eclipse in exactly the same way. They can quickly check out the project and fire up Eclipse on a new computer and just start working on it; the alternative being to configure the project manually and adding in all the jar dependencies painstakingly (if you use ant). Many open source projects do this, including the Eclipse guys, so it can't be that bad of an idea right? Right - there are benefits to checking these files in, as I've just discussed. However, each of these touted benefits create more problems, and I will discuss them in turn:

Convenience and pollution

The general argument goes that any files or metadata that helps a developer get up and rolling should be checked in. But unless the project is intended to only be developed in Eclipse, users of other IDEs will start suggesting checkins for Netbean's nbproject folder or IDEA's *.iml files. Of course, these are just the Big Three IDEs; taking the argument further would just cause lots of folders and files not directly related to the project to pollute the project space. If I wanted to take the argument even further I'd check in my own .vimrc and add an ant task to silently overwrite the developer's ~/.vimrc (but at least in that case, a clear line has been crossed).

Convenience and maintenance

Once these files are checked in, they need to be maintained. If I configure my Eclipse project differently (not unlikely as different developers have different tastes), I will see project changes in subclipse, and it will prompt me to check in my changes when I commit. This is only a minor inconvenience, but when the actual .classpath and .project files get updated, I may get conflicts, which could totally screw up my project.

Absolute paths and global classpath variables

A big part of the problem .classpath and .project files can contain absolute paths, such as the path to a jar or a path to a linked resource. Luckily, the judicious use of classpath variables can virtually eliminate this problem. For example, setting SCALA_HOME/lib/scala-library.jar as a library, instead of /home/minhuang/dev/scala/lib/scala-library.jar allows the developer to specify SCALA_HOME and have all the dependencies satisfied without absolute paths mangling the project. However, a problem still exists when working with multiple projects.

Suppose I have two locations for SCALA_HOME: one that uses the newest version, and one that uses an older version. If the library authors were nice, and the older version differs only in minor version numbers, this probably wouldn't be a problem (as you'd expect the newest version to be backwards compatible). However, the differences between major versions are usually... well, major, and you're unlikely to see compatibility. This means that different projects will need SCALA_HOME pointing to different locations, but this isn't possible, as classpath variables are shared globally.

Solution?

Many people have proposed a solution to this: do nothing. Despite all these arguments, many people still think that checking in these files is the right way to go, and maybe it is (a project with only a handful of developers who use Eclipse in exactly the same way). I don't expect any change from these people, but for a big open source project with many contributors, a better route would be to check in a project.sample and classpath.sample, similar to the way build.properties.sample is usually checked in. An ant task like ant eclipse could copy these files over to .project and .classpath respectively, adding only one extra step for those developers who use Eclipse and absolutely must have the convenience; this way, everybody wins!