22

As a strawman consider the package java.util it is a dumping ground for various classes that in most cases do not share anything in common other than the person that put them there was lazy or uninspired to come up with a more semantically correct package name for their class.

As but one example, take the class UUID what would have been a semantically correct package name for that class?

I am working on implementing my own UUID class to be more lightweight. I do not want to use me.myproject.util.UUID for my package name.

I considered me.myproject.rfc4122.UUID but that does not imply the semantic of the use of UUID.

I also considered me.myproject.uuid.UUID but I do not like the tautology in that, even though it is a popular approach in Python to put a class in a module with the same name, and packages in Java are not semantically equivalent to modules in Python.

I also considered me.myproject.UUID but rejected it because I do not want to pollute that part of the namespace with things that are not related. This just moves the problem up a level.

I also considered me.myproject.lib.UUID but this has no more semantic meaning than .util and just renames the problem.

semantics : the branch of linguistics and logic concerned with meaning.

  • How about `me.myproject.UUID`? Or `me.UUID` – Robert Harvey May 24 '15 at 05:53
  • To me, something like `from me.myproject.uuid import UUID, GetUUIDInfo` looks OK. There could be more than one exported thing in a module. – 9000 May 24 '15 at 06:34
  • 2
    JXTA has an 'id' packages for things to do with ids. – greg-449 May 24 '15 at 07:44
  • @greg-449 - I am leaning towards `identity` or `identifiers` put your suggestion with a little more explanation as an answer it will probably get accepted. –  May 26 '15 at 01:16

4 Answers4

12

The problem with trying to put each class in a package which has a semantically correct name for that class is that it tends to lead to packages that contain very few classes, or sometimes even just one class. This in turn leads to a multitude of packages.

A more pragmatic approach to package naming is to simply help you find stuff. Keeping frequently used stuff that you always know where to find all bunched up in one place keeps them out of the way and therefore makes it easier to find the more rarely used stuff. So, you do not really need package names which are semantically correct for each one of the classes that they contain, you just need package names which are not semantically incorrect. Obviously, the 'util' package name was chosen according to this line of thinking: it is not the semantically correct name for the classes it contains, but it is also not semantically incorrect, and that's good enough.

So, if this UUID type of yours is destined to only be used by this specific application, (as evidenced by the fact that you are planning to put it under 'myproject',) then it is probably part of the 'model' of your project. You should already have a 'model' package, containing the set of all classes that correspond to your persistent entities, many of which probably have relationships between them, with UUIDs probably being the means of implementing these relationships. Also, your UUIDs probably know how to persist themselves, right? And also, your UUIDs can probably only be found as members of your model entities, right? So, your model package is probably the best place for it.

Otherwise, if this UUID type of yours may be used in other projects too, then it needs to be seen as part of some framework. So, it may live in the root source folder of that framework, or in some 'types' sub-package as MainMa suggested, or even in some sub-package of that framework called 'util' or 'misc'. Nothing wrong with that.

Mike Nakis
  • 32,003
  • 7
  • 76
  • 111
  • 2
    Please try to limit commentary in answers that don't really add to the usefulness of the answer. The comment section is reserved for such disclaimers. Thank you. – maple_shaft May 26 '15 at 00:17
2

Purpose of packages is to group classes according to some criteria (package by type/layer vs. package by feature etc.). I don't really see a point to create package for just one class - especially if you don't expect there will be other classes in this package in the future.

Also I think that "util" package name is not totally meaningless - it just groups classes by a specific criteria - for me "util" class means that it is not part of the domain of the application, but it's also not a part of the framework (it doesn't influence structure of the application). It's basically just an extension of (non)standard library.

In this case I wouldn't have a problem with putting this UUID class into "util" package. If there will be some other UUID-related utility classes (like separate class for generating UUIDs), it's easy to refactor and create "util.uuid" package for them (unless you're creating a library and UUID will be part of exposed interface, then you need to be a little bit "forward-thinking").

qbd
  • 2,876
  • 1
  • 12
  • 16
  • 1
    This is my approach. It doesn't make sense to create a package that doesn't have a clear purpose. If a class can't be readily assigned to a meaningful package then 'util' is fine and maybe even preferred. Usually what happens as you go along is that enough classes end up in util that are related and they are easy to refactor out of util (at least during development) into meaningful packages. If you tried to create unique packages for each class that you don't know where it goes then you may easily miss those relationships and the opportunity to refactor into a cleaner architecture. – Dunk May 26 '15 at 16:29
  • @Dunk, that's actually a very good point - pre-maturely creating somewhat artifical package structure will prevent you to see better, more natural organization along the way. – qbd May 26 '15 at 18:37
1

Uncle Bob has some guidelines on package separation.

The first three package principles are about package cohesion, they tell us what to put inside packages:

  1. The granule of reuse is the granule of release
  2. Classes that change together are packaged together
  3. Classes that are used together are packaged together

So, answering your question, who/what is going to use the UUID class, have it as an attribute or invoke operations in it? How is your dependency graph? UUID will be used together with what other classes?

Depending on your answer, maybe you should call it the me.myproject.identity package, the me.myproject.serialization package, me.myproject.DTO or even something else entirely. Maybe, the UUID class should be kept together with your models and you will put it in a package that you already have, like me.myproject.models.

Hbas
  • 544
  • 2
  • 9
  • 1
    `dto` is about as semantically useless as `lib` or `utils`, the entire `dto` concept is a naive anti-pattern from the mid-90s, `model` falls into the same useless generalization category as well –  May 26 '15 at 22:21
  • We don´t know enough about your project to give you more useful names – Hbas May 29 '15 at 17:59
-2

First of all, UUID (with uppercase) seems like a very bad idea for the package name or class name to me, from all the styles enforced one way or another all uppercase names are associated with the "constants". Packages are intended to organise stuff, the easiest way to name a package is by the value of the classes that it holds:

  • you may choose to separate the classes by their bussines value, for example com.example.identifier;
  • or by their technical value, for example com.example.uuid.

Keep the IT simple

Tiberiu C.
  • 105
  • 2
  • 2
    Examples of ALLCAPS classes in Java: `java.util.UUID`, `java.net.URL`, `java.util.zip.CRC32`, etc. – scriptin May 24 '15 at 22:13
  • @scriptin Wouldn't be easier for a developer if he could differentiate just from the caps style a class from "constant", a member from a package name and so on ? Why do you think that CRC32, UUID is a good name for a class, just because java did it? Or because it is an acronym from "Universally unique identifier" or "cyclic redundancy check" ... but wait a bit! What is with this `java.util.zip.GZIPOutputStream` class? `GZIP` stands for ...`? there is also a `java.util.zip.ZipOutputStream` – Tiberiu C. May 24 '15 at 22:58
  • 1
    Classes are types, constants are values, there's no confusion. I don't think those names are good or bad, I'm just pointing out that (coding) styles you talk about do not enforce classes to have lowercase letters. [In Python `UUID` is uppercase too.](https://docs.python.org/2/library/uuid.html#uuid.UUID) – scriptin May 24 '15 at 23:54
  • If you see/mantain code every day, the style of it makes the difference between an "easy to read" and a "go back and forward" fiesta, isolating here just to the caps style, I think that is more valuable to express through the caps, the type of the member (class, constant, package, etc) than the fact that is an acronym. – Tiberiu C. May 25 '15 at 00:34
  • Uppercase identifier parts violate the capitalization rules for identifier naming. Word boundaries are denoted with a capital letter, therefore if there is no word boundary then there should be no capital letter, and constants are denoted with all capitals, therefore if it is not a constant, then it should not look like a constant. – Mike Nakis May 25 '15 at 09:10
  • 1
    The original question had nothing to do with what letter case to use when writing the package name is. *Semantically* UUID is not any different from Uuid, uuid, UuId, UuID, or whatever other arbitrary capitalization scheme you happen to think is "best". – Brandin May 25 '15 at 20:26
  • Yes, I know, but the "Caps" discusion escalated quickly. – Tiberiu C. May 25 '15 at 22:03
  • Depends on the language and naming conventions. I find it paradoxical that Java proclaims to use camel case, yet does not use it on classes with acronyms. `URL` should be `Url` and the various `JDBC*` classes should be `Jdbc*`. –  May 26 '15 at 00:27