What Good Error Messages Look Like

Good error messages do three things:

1. They tell me what's wrong and how to fix it.
2. They stand out.
3. They soothe my soul.

A teammate just sent me some output from Maven, a popular package manager/project manager/kitchen sink for Java. She spotted a warning, well-concealed near the top of hundreds of lines of infodump. I had to format it to make it readable.

[WARNING] Some problems were encountered while building the effective
          model for [our_project]
[WARNING] 'dependencyManagement.dependencies.dependency.(groupId:
          artifactId:type:classifier)' must be unique: org.jboss.resteasy
          :resteasy-jackson-provider:jar -> version 2.3.2.Final vs 2.3
          .0.GA @ com.[my_customer].[our_project]:[our_project]
          :0.17.Beta-SNAPSHOT, /Volumes/Workarea/trunk/pom.xml, line 272,
          column 16
[WARNING] 
[WARNING] It is highly recommended to fix these problems because they
          threaten the stability of your build.
[WARNING] 
[WARNING] For this reason, future Maven versions might no longer support
          building such malformed projects.

Gotta love the "please follow us, citizen" tone of those last few lines. I'll tell you what, Maven: either the stability of my build is really being threatened, and then you shouldn't hide this information so carefully - or it's not, and then you shouldn't be such a picky jerk. And by the way, your mother is way more malformed than my project. Sheesh.

Compare that to Homebrew, a package manager for OS X. After an operating system upgrade, I ask it whether there are any problems with my setup:

~$ brew doctor

Instead of dumping the Library of Congress to my terminal as Maven would, Homebrew gives me a clear screen with three well-formatted warnings. First one:

Warning: Some keg-only formula are linked into the Cellar.
Linking a keg-only formula, such as gettext, into the cellar with
`brew link f` will cause other formulae to detect them during the
`./configure` step. This may cause problems when compiling those
other formulae.

Binaries provided by keg-only formulae may override system binaries
with other strange results.

You may wish to `brew unlink` these brews:

    libxml2
    libxslt

I brew unlink the two libraries as instructed. Fixed. Second warning:

Warning: Some installed formula are missing dependencies.
You should `brew install` the missing dependencies:

    brew install autoconf automake libtool

Run `brew missing` for more details.

Command copy-pasted, libraries installed, problem fixed. Third warning:

Warning: /usr/bin occurs before /usr/local/bin
This means that system-provided programs will be used instead of those
provided by Homebrew. The following tools exist at both paths:

    bashbug
    clusterdb
    [more stuff]
    
Consider amending your PATH so that /usr/local/bin
occurs before /usr/bin in your PATH.

I spend a few minutes fixing the PATH. Let's try again:

~$ brew doctor
Your system is raring to brew.

That's why Maven fills my soul with darkness and desperation, while Homebrew overflows my heart with love and unicorns.