Keeping track of utility classes

Question

I've recently been more and more frustrated with a problem I see emerging in my projects code-base.

I'm working on a large scale java project that has >1M lines of code. The interfaces and class structure are designed very well and the engineers writing the code are very proficient. The problem is that in an attempt to make the code cleaner people write Utility classes whenever they need to reuse some functionality, as a result over time and as the project grows more and more utility methods crop up. However, when the next engineer comes across the need for the same functionality he has no way of knowing that someone had already implemented a utility class (or method) somewhere in the code and implements another copy of the functionality in a different class. The result is a lot of code duplication and too many utility classes with overlapping functionality.

Are there any tools or any design principles which we as a team can implement in order to prevent the duplication and low visibility of the utility classes?

Example: engineer A has 3 places he needs to transform XML to String so he writes a utility class called XMLUtil and places a static toString(Document) method in it. Engineer B has several places where he serializes Documents into various formats including String, so he writes a utility class called SerializationUtil and has a static method called serialize(Document) which returns a String.

Note that this is more than just code-duplication as it is quite possible that the 2 implementations of the above example are different (say one uses transformer API and the other uses Xerces2-J) so this can be seen as a "best-practices" problem as well...

Update: I guess I better describe the current environment we develop in. We use Hudson for CI, Clover for code coverage and Checkstyle for static code analysis. We use agile development including daily talks and (perhaps insufficient) code reviews. We define all our utility classes in a .util which due to it's size now has 13 sub-packages and about 60 classes under the root (.util) class. We also use 3rd party libraries such as most of the apache commons jars and some of the jars that make up Guava.

I'm positive that we can reduce the amount of utilities by half if we put someone on the task of refactoring that entire package, I was wondering if there are any tools which can make that operation less costly, and if there are any methodologies which can delay as much as possible the problem from recurring.

Harville

See #4189419 – Reynaldoreynard

I imagine you can also adapt that solution to list all methods with duplicate type signatures. – Reynaldoreynard

Answer 1

Your problem is a very common one. And a real problem too, because there is no good solution.

We are in the same situation here, well I'd say worse, with 13 millions line of code, turnover and more than 800 developers working on the code. We often discuss about the very same problem that you describe.

The first idea - that your developers have already used - is to refactor common code in some utility classes. Our problem with that solution, even with pair programming, mentoring and discussion, is that we are simply too many for this to be effective. In fact we grow in subteams, with people sharing knowledge in their subteam, but the knowledge doesn't transit between subteams. Maybe we are wrong but I think that even pair programming and talks can't help in this case.

We also have an architecture team. This team is responsible to deal with design and architecture concerns and to make common utilities that we might need. This team in fact produces something we could call a corporate framework. Yes, it is a framework, and sometimes it works well. This team is also responsible to push best practices and to raise awareness of what should be done or not, what is available or what is not.

Good core Java API design is one of the reason for Java success. Good third party open sources libraries count a lot too. Even a small well crafted API allows to offer a really useful abstraction and can help reduce code size a lot. But you know, making framework and public API is not the same thing at all as just coding an utility class in 2 hours. It has a really high cost. An utility class costs 2 hours for the initial coding, maybe 2 days with debugging and unit tests. When you start sharing common code on big projects/teams, you really make an API. You must ensure perfect documentation then, really readable and maintainable code. When you release new version of this code, you must stay backward compatible. You have to promote it company wide (or at least team wide). From 2 days for your small utility class you grow to 10 days, 20 days or even 50 days for a full-fledged API.

And your API design may not be so great. Well, it is not that your engineers are not bright - indeed they are. But are you willing to let them work 50 days on a small utility class that just help parsing number in a consistent way for the UI? Are you willing to let them redesign the whole thing when you start using a mobile UI with totally different needs? Also have you noticed how the brightest engineers in the word make APIs that will never be popular or will fade slowly? You see, the first web project we made used only internal frameworks or no framework at all. We then added PHP/JSP/ASP. Then in Java we added Struts. Now JSF is the standard. And we are thinking about using Spring Web Flow, Vaadin or Lift...

All I want to say is that there is no good solution, the overhead grows exponentially with code size and team size. Sharing a big codebase restricts your agility and responsiveness. Any change must be done carefully, you must think of all potential integration problems and everybody must be trained of the new specificities and features.

But the main productivity point in a software company is not to gain 10 or even 50 lines of code when parsing XML. A generic code to do this will grow to a thousand lines of code anyway and recreates a complex API that will be layered by utility classes. When the guy make an utility class for parsing XML, it is good abstraction. He give a name to one dozen or even one hundred lines of specialized code. This code is useful because it is specialized. The common API allows to work on streams, URL, strings, whatever. It has a factory so you can choose you parser implementation. The utility class is good because it work only with this parser and with strings. And because you need one line of code to call it. But of course, this utility code is of limited use. It works well for this mobile application, or for loading XML configuration. And that's why the developer added the utility class for it in the first place.

In conclusion, what I would consider instead of trying to consolidate the code for the whole codebase is to split code responsibility as the teams grow:

• transform your big team that work on one big project into small teams that work on several subprojects;
• ensure that interfacing is good to minimize integration problems, but let team have their own code;
• inside theses teams and corresponding codebases, ensure you have the best practices. No duplicate code, good abstractions. Use existing proven APIs from the community. Use pair programming, strong API documentation, wikis... But you should really let different teams make their choices, build their own code, even if this means duplicate code across teams or different design decisions. You know, if the design decisions are different this may be because the needs are different.

What you are really managing is complexity. In the end if you make one monolithic codebase, a very generic and advanced one, you increase the time for newcomers to ramp up, you increase the risk that developers will not use your common code at all, and you slow down everybody because any change has far greater chances to break existing functionality.

Tallulah

thanks for your answer, I think you are right. The next logical step for us is breaking up our code into subprojects and defining interfaces where the shared code is minimal. We have been talking about it for a while and I feel that it will provide the compromise we search for. Since I'm not sure any tool exists which can help me solve this I'm awarding the bounty to you, as you are probably closest to defining a way to mitigate the problem – Harville

50 days split over 800 potential users is not that much of a overhead – Garnierite

Nobody want to pay 50 days for a thing that could be done in 2 days. And if you have to do it because you have a big team, then this big team is in fact decreasing productivity. – Tallulah

Answer 2

A good solution to this problem is to start adding more object-orientation. To use your example:

Example: engineer A has 3 places he needs to transform XML to String so he writes a utility class called XMLUtil and places a static toString(Document) method in it

The solution is to stop using primitive types or types provided by the JVM (String, Integer, java.util.Date, java.w3c.Document) and wrap them in your own project-specific classes. Then your XmlDocument class can provide a convenient toString method and other utility methods. Your own ProjectFooDate can contain the parsing and formatting methods that would otherwise end up in various DateUtils classes, etc.

This way, the IDE will prompt you with your utility methods whenever you try to do something with an object.

Libb

Yep, definitely move towards more of a domain driven model/ hexagonal architecture – Cleavland

Answer 3

There are several agile/ XP practices you can use to address this, e.g.:

• talk with each other (e.g. during daily stand-up meeting)
• pair programming/ code review

Then create, document & test one or several utility library projects which can be referenced. I recommend to use Maven to manage dependecies/ versions.

Inverter

we are slowly moving towards this solution by externalizing more and more utilities into different jars (kinda like apache commons). However, there is still the problem of then ordering the utlities within those jars (what belongs where and where should I look) I know communication is imperative but different people work on different parts of the code and without some way for an engineer to access the data he is bound to miss something – Harville

Maybe I'am wrong, but a code base with 1 million line of code is too big so you can't hope managing code duplicated just with talking and pair programming. – Tallulah

Answer 4

You might consider suggesting that all utility classes be placed in a well organized package structure like com.yourcompany.util.. If people are willing to name sub packages and classes well, then at least if they need to find a utility, they know where to look. I don't think there is any silver bullet answer here though. Communication is important. Maybe if a developer sends a simple email to the rest of the development staff when they write a new utility, that will be enough to get it on people's radar. Or a shared wiki page where people can list/document them.

Groundsill

we do use the .util package structure, however as the number of utilities grow it becomes a problem finding the right tool for the job which again ends up with more classes. a Wiki about all available utils might be an option but then finding the information in the wiki is (roughly) the same problem as finding the information in the Javadoc. – Harville

Answer 5

1. Team communication (shout out "hey does someone have a Document toString?")
2. Keep utility classes to an absolute minimum and restrict them to a single namespace
3. Always think: how can I do this with an object. In your example, I would extend the Document class and add those toString and serialize methods to it.

Oralla

I believe we are doing a good effort in keeping common functionality in base classes, however, often times extension is not an option, org.w3c.Document being a prime example. Perhaps we can do better in moving more logic into base classes, but how would I find all existing utility methods which can be moved into base classes? – Harville

@well, one way would be to grep around for "public static" or some such pattern in the relevant folders. And yeah, I feel you on the "sealed" base classes. In those cases you can always use the decoration patter to wrap Document into your own version of it. – Oralla

Answer 6

This problem is helped when combining IDE "code-completion" features with languages which support type extensions (e.g. C# and F#). So that, imagining Java had a such a feature, a programmer could explore all the extension methods on a class easily within the IDE like:

Document doc = ...
doc.to //list pops up with toXmlString, toJsonString, all the "to" series extension methods

Of course, Java doesn't have type extensions. But you could use grep to search your project for "all static public methods which take SomeClass as the first argument" to gain similar insight into what utility methods have already been written for a given class.

Gastongastralgia

do you know of any tool or eclipse plugin which can do this easily? asking all programmers to grep their util package before adding any static methods seems like a pain and I'm afraid the request will most likely be ignored for it's overly complex nature. – Harville

Sorry @Asaf, I do not know of such a ready made tool. But I think that this could be a fun little project. I don't use grep much, but I imagine the pattern is reasonably simple and easily reusable for any class. Once you get that down, you could create a script which takes a class name as the only input and runs the command. That would get the job done with little burden on all the programmers, I think. But yeah, it would be great to have an Eclipse plugin where you right click a class name and choose ("find all utility methods")... that could be a fun project too! – Gastongastralgia

upvoting your comment for giving me an idea for my next "free" sprint – Harville

Answer 7

Its pretty hard to build a tool that recognizes "same functionality". (In theory this is in fact impossible, and where you can do it in practice you likely need a theorem prover).

But what often happens is people clone clode that is close to what they want, and then customize it. That kind of code you can find, using a clone detector.

Our CloneDR is a tool for detecting exact and near-miss cloned code based on using parameterized syntax trees. It matches parsed versions of the code, so it isn't confused by layout, changed comments, revised variable names, or in many cases, inserted or deleted statements. There are versions for many languages (C++, COBOL, C#, Java, JavaScript, PHP, ...) and you can see examples of clone detection runs at the provided link. It typically finds 10-20% duplicated code, and if you abstract that code into library methods on a religious base, your code base can actually shrink (that has occurred with one organization using CloneDR).

Hannah

Answer 8

You are looking for a solution that can you help you manage this inevitable problem, then I can suggest a tool:

• TeamCity: an amazing easy to use product that manages all your automated code building from your repository and runs unit tests etc.
  It's even a free product for most people.
  The even better part: it has built in code duplicate detection across all your code.
  

More stuff to read up:

• Tools to detect duplicated code (Java)

Rajasthani

Answer 9

1. a standard application utility project. build a jar with the restricted extensibility scope and package based on functionality.
2. use common utilities like apache-commons or google collections and provide an abstraction
3. maintain knowledge-base and documentation and JIRA tracking for bugs and enhancements
4. evolutionary refactoring
5. findbugs and pmd for finding code duplication or bugs
6. review and test utility tools for performance
7. util karma! ask team members to contribute to the code base, whenever they find one in the existing jungle code or requiring new ones.

Berryman