What's a YAUL? Or a YAUC?

Hani has a very valid post about util libraries.

Libraries that just have a bunch of non focussed utils in them, rarely provide a benefit to anyone other than the original authors.

When developers are looking into using a third party library, it is for a specific reason. A library that has a specific focus may meet this requirement, whereas an all-purpose util library rarely will (and even if it does, it is unlikely that it will be found).

Much of the code within the library may serve little purpose outside the context of the application it was originally built for, but not necessarily all.

By identifying the code within that has defined focus, you can extract that out and provide a library with a specific purpose.

Example

Whilst developing many parts of OpenSymphony (and our own bespoke applications that use OpenSymphony), we noticed there were many odd little methods that we found useful, which lead to the conclusion that other people would also find them useful. We slapped them together into a util library and OSCore was born.

This library lacked a clear responsiblity and in the end became a dumping ground for code that didn't seem to belong elsewhere. As a consequence, it wasn't successful. No one is going to choose to use a library that does this, that, a bit of this and has that really useful method there.

Eventually this was learned and the one part of the library that had a clearly defined use (PropertySet) was split out into its own project. Today, PropertySet is a well used library, whereas the rest of OSCore has faded into the background.

Incidently, this is a lesson we learned early on in OpenSymphony and the result has been many quality components since, many of which I rely on today.

YAUCs

As well as libraries, this also applies to individual classes. A class named CheeseUtil express very little about the focus of the class other than it's got something to do with cheese. As a result util classes often grow fairly big and lack clear design (in fact, they often end up as a bunch of public static methods).

In this case a util class can be refactored into many smaller classes which can each flourish on their own, with their own design.

YAUC Example

In OSCore there's a class called XMLUtils.

From the JavaDoc:

XMLUtils is a bunch of quick access utility methods to common XML operations.

These include:

• Parsing XML stream into org.w3c.dom.Document.
• Creating blank Documents.
• Serializing (pretty-printing) Document back to XML stream.
• Extracting nodes using X-Path expressions.
• Cloning nodes.
• Performing XSL transformations.

Authors: Joe Walnes, Hani Suleiman :)

Unless someone had specifically looked at the JavaDoc or methods of every single class in the system, there would be little chance of knowing that.

Breaking this class up into many smaller classes, errm, objects such as XMLParserFacade, XMLPrettyPrinter, NodeCloner, XPathEvaluator and XSLTransformere, expresses the intent clearer and is much more likely to be found.

(Hani and I have since learned from these mistakes).

Conclusion

Small and clearly defined responsibilities for libraries and individual classes results in improved reuse as they have an increased chance of meeting part of a developer's requirement.

Comments

Wei Li

While I agree we can do a lot from design point of view to increase the reusability, one thing that bothers reusability is quick tutorials and test cases. People learn by example and the javadoc api is not enough. Short code examples beat lots of other things.

When I looked into your Sqluiggle and XStream, the first I did was clicking the link to the Two Minute Tutorial. I saw right away how I can use them in the future, at which point I may invest more time and effort to dive into it if needed. I can only wish there are plenty of this kind of tutorials around.

Henri Yandell

I've pondered how such tutorials could be created for the Jakarta Commons util children [Lang, Collections, IO, Codec, others], but for much of Lang I found myself just repeating what was in the javadoc.

2 minute tutorial for StringUtil:

String name = StringUtils.capitalize("fred")

etc.

If the use of something is more than a single method call, a tutorial is needed, otherwise javadoc is the correct solution.

Henri Yandell

The original intent of XxxUtils at Jakarta Commons is that it is "a class of static methods that act upon an object of type Xxx".

So XmlUtils is a bad name [if seen at Commons] because it does not act upon Xml, but rather a DOM Element object, so should be called ElementUtils etc [stretched example].

Name:
Email:
URL: