DON’T deprecate because you intend to re-write at some point. Wait until you’ve actually produced the replacement or at least know when the replacement will be available. Marking all code you’re displeased with doesn’t help anyone, use “TODO” comments or something else for that.

DO document what alternative to the deprecated code to use instead.

DO document why the code is deprecated. It could be from everything from aesthetic to important security reasons, so your users may want to know.

DO, if possible, re-implement deprecated code in terms of its replacement. This will both ensure that things continue to work and instruct how to update calling code.

DON’T use deprecation if all callers are within your own code base. Just update the callers and remove the code.

DON’T deprecate a method if there’s no real alternative. E.g. if you know a method is needed but don’t like that it breaks encapsulation you can discourage its use in documentation, but if you use @deprecated all calling code will be plagued with useless warnings.

Verbosity

Maybe the problem is spelled “XML”.

Buildr shows that you can express essentially the same things as Maven’s pom files in an order of magnitude fewer lines and still be more readable. Good old Ant has the excuse of being created in a time when XML was hyped, but there’s no excuse for the masses of XML that Maven forces you to create and maintain.

Working With Legacy Code

Have you ever tried to introduce Maven to build a large legacy system? Because of Maven’s inflexibility, you can’t easily do this in small steps, incrementally moving closer to (Maven’s idea of) an ideal file and dependency structure. Instead you’re looking at doing it all in a single huge, messy, risky step.

Transitive Dependencies

Nice in theory. In practice this means Maven will download half the internet for you and at the same time making you sensitive to every minor slip-up in any pom of any n-level indirect dependency you have.
Even if your code never invokes the rarely used parts of commons-something that actually depends on commons-kitchen-sink, you’re going to get commons-kitchen-sink. Or maintain the screenful of XML to override it.

Flexibility and Plugins

Most non-trivial projects have at least one detail that just doesn’t fit Maven’s model. In any other build tool that can be easily remedied with (often just a single line of) scripting. In Maven, the solution is plugins.
So your build ends up depending on abandoned third-party plugins just to accomplish the most trivial scripting tasks. So much for dependency management.

Unit Testing

When unit testing, you are only interested in two things: Are my tests at 100% and, if not, what is failing? (And, for bragging rights, how many tests do I have?) Just like Ant before it, Maven fails badly at this.
The (mostly useless) stdout from the tested code is puked to the terminal, drowning Maven’s own test summaries. The causes of failures, on the other hand, are hidden away in report files in some other directory.

I can see the use for “test reports” in some scenarios and tool sets, but as a default behavior for a unit test runner they’re absurd.

Build Output

Why is so much useless output written to the terminal during a build? Are they trying to impress Linux Kernel hackers?

Repositories

It’s good practice to keep the things you depend on under version control, among other things for repeatability. Maven’s take on this is to keep dependency meta-data under version control, and download the dependencies themselves from public repositories.
So now you’re depending on someone else’s public repository to be available (and correctly configured and maintained). If it’s not, you won’t be able to build on a freshly installed machine.
I’m told the recommended solution is to have your own local caching repo (which also allows you to depend on private or proprietary libraries). So now you have yet another server to maintain. Wouldn’t it be both less work and lower risk to just keep the jars under local version control?

(Also, the only caching repo I have tried, Artifactory, kept corrupting data. It was probably a problem with its embedded Jackrabbit content repository, but still).

File Structure

I’m forced to structure my files in a way the Maven developers, a group whose judgement and taste I usually dissent with, find ideal.

I could go on all day…

  210    cd
   81    ls
   29    more
   28    ant
   25    bin/polopoly
   15    svn
   11    sudo
    9    pwd
    8    irb
    7    fgrep

1. Verify beforehand that your bootable backup disk actually is bootable.

2. Having a replacement disk ready means less when you don’t have the Torx T8 screwdriver needed to install it.

3. Torx screws are an evil conspiracy.

4. Having a working DVD reader will save you time and money when re-installing the OS.

But I luckily made the last backup just 24h before the crash, so I lost almost nothing.

This is a common use of try-catch:

public void foo() {
    // Catch any exception so that the call to super is done anyway
    try {
        //...
    } catch (Exception e) {
        // Log
        // ...
    }
    // Call super last
    super.foo();
}

You could think that the purpose of the try-catch is to enable logging of the exception. But the first comment (taken from actual example code) suggests that the logging is just incidental. The purpose is to make sure that something is run no matter what. The logging is just a case of not knowing anything better to do with the exception once it’s caught.

Instead, why not use the simple try-finally:

public void foo() {
    try {
        //...
    } finally {
        super.foo();
    }
}

We’re not “handling” the exception, but that’s probably good. We are handling non-Exception throwables though. I think people just forget that you can have a try-finally without the catch.

If you’re in London before 31 August 2008, go see it!

The good old toString() method, with us since Java 1.0, has at least two different meanings:

• Displaying: How the object should appear to the user, in the GUI, on a web page, etc.
• Inspection: How the object should appear in debug output, logs, debugger tools etc.

Both are in some way “a string representation of the object”. The default implementation in java.lang.Object suggests inspection, e.g. “java.lang.Object@c37f31”, but many APIs, like AWT/Swing, use it for displaying the object to the user.

Problems

• It’s hard to tell which usage is intended when reading the code.
• Debuggers will use toString(), which can cause confusing side-effects.
• Since every object has a toString(), the IDE’s usage search becomes unusable.
• It’s hard to tell if a toString() method is dead code or not.

In addition, a lot of code implements it when it has a more specific meaning. For instance, generating HTML is better done as toHTML() than as toString().

What Others Do

Ruby solves this differently than Java. There are two methods, inspect() and to_s(), where the default implementation of to_s() in Object uses inspect(). This separates the two intentions, but still has to_s() available on every object.

We can’t do much about java.lang.Object, but we still have options.

Suggestion

Use toString() only for logging and debug output.

If the method has a more specific meaning, communicate that instead, e.g. title() or name().

If the value to display has a specific format you can communicate that instead, e.g. toHTML() or asLeetSpeak().

If the value to display is nothing other than a string, still avoid toString(). Call it something like displayString(), or maybe even asString() to avoid problems.

Sorting

BigDecimal’s compareTo method relies on both of the BigDecimals being in the same internal form. Internally BigDecimal uses either a BigInteger or, when possible, a native integer to represent its value. To compare two BigDecimals they’re both normalized (“inflated”) to the BigInteger form. This means that simply sorting a list of BigDecimals can cause memory use to increase. Not what you’d expect.

Serialization

Serialization of BigDecimal is surprisingly slow. Not only do they inflate their internal representation, just like when comparing, but they also use a lot of CPU for some reason. When serializing large graphs of objects of a lot of different classes, the BigDecimals stood out like a sore thumb in the CPU profile. Dumping them as String representations instead was quicker and didn’t use as much memory.