Utility classes are wrong

Every­one has some­where on a PC a di­rec­to­ry called “mis­cel­la­neous”, or sim­ply “misc.” This is where we put or­phaned stuff which haven't found its place some­where else, grouped with sim­i­lar files in a well-named di­rec­to­ry. For some peo­ple, the desk­top di­rec­to­ry is the ac­tu­al lo­ca­tion for mis­cel­la­neous stuff.

In a sim­i­lar man­ner, most pro­jects I've seen de­vel­oped over time a tu­mor and gave it an ugly name “util­i­ty.” What hap­pen is that the pro­ject grows or­gan­i­cal­ly, and the ar­chi­tec­ture and over­all code or­ga­ni­za­tion doesn't nec­es­sar­i­ly keep up, ei­ther be­cause the team doesn't have time for refac­tor­ing, or be­cause no­body has enough knowl­edge of the over­all pro­ject struc­ture, or sim­ply be­cause no one cares. Dis­crep­an­cies ap­pear, and soon­er or lat­er, some­one cre­ates a class which doesn't fit well any­where. So the class end up in a name­space or pack­age which has “util­i­ty” in its name.

The sec­ond en­counter of the “mis­cel­la­neous”-type tu­mor doesn't have a sin­gle pro­ject as its scope, but ei­ther a bunch of pro­jects or, po­ten­tial­ly, all the pro­jects of a com­pa­ny. What hap­pens is that some­one, some­where, needs for a pro­ject to use some code which was al­ready writ­ten for a dif­fer­ent pro­ject with­in the same com­pa­ny. With all the good in­ten­tions, the de­vel­op­er, in­stead of du­pli­cat­ing code, makes a shared li­brary or pack­age and, to high­light the reusable as­pect of the new li­brary, calls it “util­i­ty.”

In the fol­low­ing two sec­tions, I'll ex­plain why both us­ages of “util­i­ty” word are prob­lem­at­ic by them­selves and in­dica­tive of a larg­er is­sue.

“Util­i­ty” as a part of a pro­ject

When ear­li­er in this ar­ti­cle I was talk­ing about the “mis­cel­la­neous” di­rec­to­ry, I said noth­ing about the rea­sons which lead to the cre­ation of such di­rec­to­ry in the first place. The mu­tu­al­ly ex­clu­sive as­pect of di­rec­to­ries cou­pled with a flawed tree struc­ture are the ma­jor rea­sons we end up with the mess. Giv­en the rigid­i­ty of file sys­tem tree struc­tures and the fact that an es­tab­lished struc­ture don't evolve eas­i­ly, it is not sur­pris­ing that many files can­not find their way in the hi­er­ar­chy.

Code source as well takes a form of a lim­it­ed-depth typed-lev­els tree struc­ture. Li­braries con­tain pack­ages. Pack­ages con­tain class­es. Class­es con­tain meth­ods. As with the file struc­ture, some class­es and meth­ods will fit per­fect­ly well with­in the ex­is­tent struc­ture, while oth­ers will tend to be­come mar­gin­als.

When the class­es or meth­ods which don't find their way in the cur­rent code struc­ture are la­beled as “util­i­ty,” this sim­ply means that the team was un­able to adapt the struc­ture to the new­com­er. As I said at the be­gin­ning of this ar­ti­cle, there may be mul­ti­ple rea­sons for that, but in­de­pen­dent­ly of the rea­son, the pres­ence of such class­es or meth­ods is in­dica­tive of a lega­cy struc­ture which wasn't refac­tored over time. This shouldn't hap­pen in a cor­rect­ly main­tained pro­ject.

An­oth­er pos­si­bil­i­ty is that the thing which was la­beled as util­i­ty was ac­tu­al­ly put in the right place with­in the code hi­er­ar­chy, but just in­cor­rect­ly named. This, in­deed, hap­pens a lot. There are two rea­sons for that:

• Find­ing good names is dif­fi­cult. While, in­deed, this is not an easy task, this is not a rea­son to use gener­ic terms such as “util­i­ty” or “busi­ness.” All ap­pli­ca­tion code is busi­ness code. All ap­pli­ca­tion code is util­i­ty code. Please, don't use terms which bring no mean­ing.

• There seem to be a mag­i­cal mean­ing to the word “util­i­ty.”

  Some peo­ple seem to use it as an op­po­si­tion to “busi­ness,” in a sense that all code which has some ex­clu­siv­i­ty to the pro­ject is busi­ness code, while all code which could be found in any pro­ject would be util­i­ty code. This dis­tinc­tion makes me par­tic­u­lar­ly ner­vous: the bor­der be­tween the two is all but clear. For in­stance, would a rule used to gen­er­ate an in­voice based on the spe­cif­ic char­ac­ter­is­tics of air­plane parts be char­ac­ter­ized as a busi­ness rule be­cause it is spe­cif­ic to the in­ter­nal pur­chas­ing plat­form used by Boe­ing? Great, now what if Air­bus has the ex­act same rule in a dif­fer­ent pro­ject? The same goes for so-called util­i­ty code. Is code which sends e-mail util­i­ty code? Would we re­al­ly need this code on a shrink-wrap soft­ware for bi­ol­o­gists which process­es DNA sam­ples? Or maybe on em­bed­ded soft­ware which con­trols the au­to­mat­ed trains in a sub­way?

  There are oth­er per­vert­ed uses of this word. Many de­vel­op­ers be­lieve that util­i­ty code means sta­t­ic class­es with func­tions in them. Not only the term “util­i­ty” is still mean­ing­less in this con­text, but the whole idea is wrong in a con­text of an ob­ject-ori­ent­ed lan­guage, giv­en how those so-called util­i­ty func­tions are im­ple­ment­ed, and leads to in­flex­i­ble and un­friend­ly code.

“Util­i­ty” as a li­brary shared across pro­jects

Shar­ing code be­tween pro­jects pre­vents du­pli­ca­tion, which is a Good Thing™ in any sit­u­a­tion. And so, com­pa­nies cre­ate util­i­ty li­braries which grow, and grow, and grow over time. Their growth is usu­al­ly hor­i­zon­tal; in oth­er words, new com­po­nents are added to a col­lec­tion of old ones. All com­po­nents be­ing rel­a­tive­ly in­de­pen­dent—there is re­al­ly few things in com­mon be­tween se­ri­al­iz­ing an ob­ject to JSON, log­ging an event, read­ing a file and cre­at­ing a trans­ac­tion over a net­work—the term “util­i­ty” is of­ten used by the lack of a bet­ter al­ter­na­tive (per­son­al­ly, I pre­fer “Ali Baba,” but since I re­cent­ly ex­plained that cul­tur­al ref­er­ences have no place in our code, I'm afraid that the term won't stick well with­in the com­mu­ni­ty.)

The prob­lem here is that as the li­brary grows, it be­comes more and more cum­ber­some. In­stead of ex­plain­ing the con­cept it­self, I will bare­ly give two ex­am­ples from two ecosys­tems.

• Imag­ine if all Python's code you use was in a sin­gle pack­age. You need to parse CSV files? Yep, import utility is what you do. Need to work with dates? That would be import utility. Any­one wants to work with reg­u­lar ex­pres­sions? That's clear­ly util­i­ty code.

• Imag­ine if all .NET Frame­work, as well as every as­sem­bly cre­at­ed by Mi­crosoft and the most pop­u­lar NuGet pack­ages, were in the same as­sem­bly. You need to print “Hel­lo World” to a con­sole? Here's the util­i­ty as­sem­bly, it can do that; do not pay at­ten­tion to all those Share­Point class­es. What is here? It's MEF, you don't re­al­ly need it to print text to con­sole, but it could be handy to have it if you need it one day. As well as Boot­strap-re­lat­ed code; handy too.

This mess is ex­act­ly what com­pa­nies tend to pro­duce when they cre­ate the “util­i­ty” pro­ject for every­thing which is used by two or more pro­jects.

The so­lu­tion? Cre­ate sep­a­rate pack­ages or li­braries. If two pro­jects share code which pro­duces EDI in­voic­es, cre­ate an ED­I­FACT pack­age for that. Name it ED­I­FACT. The next time when you cre­ate code which gen­er­ates se­cure pass­words based on some fan­cy cri­te­ria, cre­ate a sep­a­rate pack­age for that and name it ac­cord­ing­ly. Don't mix it with EDI un­der the “util­i­ty” um­brel­la, be­cause de­vel­op­ers who need to gen­er­ate in­voic­es may not nec­es­sar­i­ly need to gen­er­ate pass­words, and de­vel­op­ers who work with pass­words may nev­er hear about ED­I­FACT.

The abil­i­ty to run pri­vate npm, pypi or NuGet repos­i­to­ries means that you don't even need to han­dle de­pen­den­cies your­self, even for pro­jects which are not open sourced. So for your own's good, please, don't put to­geth­er things which have noth­ing to do: keep them sep­a­rate, and reuse the ones you need to, when you need to.