514

How should one separate words in package names? Which of the following are correct?

  1. com.stackoverflow.my_package (Snake Case using underscore)
  2. com.stackoverflow.my-package (Kebab Case using hyphens)
  3. com.stackoverflow.myPackage (Camel Case)
  4. com.stackoverflow.MyPackage (Pascal Case)

What is the general standard?

Ahmed Nabil
  • 17,392
  • 11
  • 61
  • 88
Jigar
  • 8,762
  • 6
  • 25
  • 26

6 Answers6

411

All three are not the conventions.

Use com.stackoverflow.mypackage.

The package names do not follow camel casing or underscores or hyphens package naming convention.

Also, Google Java Style Guide specifies exactly the same (i.e. com.stackoverflow.mypackage) convention:

5.2.1 Package names

Package names are all lowercase, with consecutive words simply concatenated together (no underscores). For example, com.example.deepspace, not com.example.deepSpace or com.example.deep_space.

— Google Java Style Guide: 5.2 Rules by identifier type: 5.2.1 Package names.

Sergey Vyacheslavovich Brunov
  • 17,291
  • 7
  • 48
  • 81
bragboy
  • 34,892
  • 30
  • 114
  • 171
  • 11
    I partially agree - they are not 'wrong' according to the java naming conventions but they shouldn't be used in my opinion. (http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html) – Andreas Dolk Jul 05 '10 at 12:00
  • @Andreas_D the link you provided states that "The prefix of a unique package name is always written in all-lowercase ASCII letters" – Jose Gómez Oct 26 '15 at 20:12
  • 1
    @JoseGómez "The _prefix_". So imho this does not exclude all other words comprising a package name from being CamelCase or snake_case – Antek Jan 03 '19 at 13:51
  • 4
    I have been following this convention. However, the readability really isn't very good. What is the reason behind all lower cases? – Haomin Apr 19 '21 at 16:45
  • 8
    Using underscore is suggested in the Java package naming convention page, linked in the answer. Eg: "org.example.hyphenated_name" – Debanshu Kundu Nov 12 '21 at 15:36
  • 4
    @Haomin : the reason is that packages use the underlying file system, which might be case-sensitive or case-unsensitive. In the case of multi-developers, multi-platform project, it might lead to problems for folder names. – khaemuaset Aug 25 '22 at 09:22
  • (This being said, the JSL still contain a number of example of camelcase packages, such as `morePoints`) As a number of IDE flag non-lowercases package names with a warning, I'd be however curious to know when and whence this idea of all-lowercases package comes ? – khaemuaset Aug 25 '22 at 09:41
299

Here's what the official naming conventions document prescribes:

Packages

The prefix of a unique package name is always written in all-lowercase ASCII letters and should be one of the top-level domain names, currently com, edu, gov, mil, net, org, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166, 1981.

Subsequent components of the package name vary according to an organization's own internal naming conventions. Such conventions might specify that certain directory name components be division, department, project, machine, or login names.

Examples

  • com.sun.eng
  • com.apple.quicktime.v2
  • edu.cmu.cs.bovik.cheese

References

Note that in particular, anything following the top-level domain prefix isn't specified by the above document. The JLS also agrees with this by giving the following examples:

  • com.sun.sunsoft.DOE
  • gov.whitehouse.socks.mousefinder
  • com.JavaSoft.jag.Oak
  • org.npr.pledge.driver
  • uk.ac.city.rugby.game

The following excerpt is also relevant:

In some cases, the internet domain name may not be a valid package name. Here are some suggested conventions for dealing with these situations:

  • If the domain name contains a hyphen, or any other special character not allowed in an identifier, convert it into an underscore.
  • If any of the resulting package name components are keywords then append underscore to them.
  • If any of the resulting package name components start with a digit, or any other character that is not allowed as an initial character of an identifier, have an underscore prefixed to the component.

References

William Stanley
  • 693
  • 1
  • 7
  • 22
polygenelubricants
  • 376,812
  • 128
  • 561
  • 623
  • 64
    Chapter 7.7 even recommends using the underscore in package names! – Andreas Dolk Jul 05 '10 at 12:27
  • 2
    Updated references: http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.1 http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.1 (there is no more 6.8.1 and 7.7) – Victor Jan 30 '13 at 14:28
  • 8
    Here: http://www.oracle.com/technetwork/java/codeconventions-135099.html it says all-lower, but here http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.1 it says that the first component should be in lower case, also they removed examples of upper case word separation. Also here: http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html it says all-lower case. So it seems that upper case in package names is currently discouraged. – dhblah Mar 06 '14 at 08:35
  • 52
    Chapter 7.7 does not recommend using underscores, it recommends replacing special/invalid symbols with an underscore which is quite far from just recommending for general usage. – eduard.dudar Oct 26 '16 at 01:10
37

Anyone can use underscore _ (its Okay)

No one should use hypen - (its Bad practice)

No one should use capital letters inside package names (Bad practice)

NOTE: Here "Bad Practice" is meant for technically you are allowed to use that, but conventionally its not in good manners to write.

Source: Naming a Package(docs.oracle)

Himanshu Mori
  • 873
  • 1
  • 10
  • 20
  • 103
    Yes, using a hyphen is bad practice, because it is an error. And writing code that doesn't compile is indeed bad practice. – glglgl May 26 '17 at 07:01
  • Good link - helps give all this some context when you know what the source says. I'm used to all lower case convention as well. But according to the docs, looks like it is simply a matter of choice/style . I have added a comment to the specific post asked about camel case for package names *(which I don't think is a duplicate of this post , btw - which just asks about the convention in general)* https://stackoverflow.com/questions/36755783/can-we-use-camel-case-in-java-package-naming – Gene Bo Oct 15 '18 at 20:58
  • "No capital letters", although I would agree that all caps or something that looks like a ClassName is a bad idea, it also eliminates thisExample. Saying "it's bad practice" is about the most unconvincing, vague and meaningless reason I can think of. Can this be elaborated on? (i.e. define 'bad practice') – Manius Jun 04 '19 at 20:45
  • You're still basically saying "it's bad" without giving justification why it should be considered bad. Does it break tooling? Create confusion? Is it harder to read or type? For the examples given I think we can answer yes to many of those. But I can't understand an *absolute* ban on capital letters. A package name LikeThis (like a class name) is obviously confusing, but likeThis isn't confusing to me and seems more readable for a two word package name like bigdataSource (vs "bigdatasource"). Unless there's some reason camelCase is a bad idea for packages that I'm unaware of, that seems fine. – Manius Jun 12 '19 at 16:31
  • Turns out I missed this: https://www.oracle.com/technetwork/java/codeconventions-135099.html All lowercase is part of Oracle's package name convention. I still think that's a rather crappy convention to rule out camel case which starts lower, for those (rare) times when you need to use a two word package name and it doesn't make sense to make it two directories. But oh well. – Manius Jun 12 '19 at 16:37
  • The document says "The prefix of a unique package name is always written in all-lowercase...". My reading of it is that it refers to the prefix that tries to mirror the top level domain name, not the whole package name. But looks like people have standardize with all lowercase. – Juanpa Apr 23 '21 at 01:22
  • The question is about the conventions used when naming a package that consists of two or more words such as "mypackage" (or however you'd name it). The link you gave is about handling a hyphen or other illegal characters in a package when using your domain in reverse order to prefix a package or when using a reserved word like `int` in your package. – user904963 Feb 08 '22 at 05:42
20

The official naming conventions aren't that strict, they don't even 'forbid' camel case notation except for prefix (com in your example).

But I personally would avoid upper case letters and hyphenations, even numbers. I'd choose com.stackoverflow.mypackage like Bragboy suggested too.

(hyphenations '-' are not legal in package names)

EDIT

Interesting - the language specification has something to say about naming conventions too.

In Chapter 7.7 Unique Package Names we see examples with package names that consist of upper case letters (so CamelCase notation would be OK) and they suggest replacing hyphenation by an underscore ("mary-lou" -> "mary_lou") and prefix java keywords with an underscore ("com.example.enum" -> "com.example._enum")

Some more examples for upper case letters in package names can be found in chapter 6.8.1 Package Names.

Pang
  • 9,564
  • 146
  • 81
  • 122
Andreas Dolk
  • 113,398
  • 19
  • 180
  • 268
  • 2
    As Andreas has noted, there's no *rules* about using upper casing in package names. One specific reason to avoid it is that I have seen people run into problems with mixed case package names when doing cross platform development. Especially when someone decides to rename or change the case of a package, you're then relying on both your VCS and development environments to do *exactly* the right thing with the directory case. – Shorn Oct 01 '14 at 01:52
  • 2
    Actually, there are rules: "The prefix of a unique package name is always written in all-lowercase ASCII letters" (http://www.oracle.com/technetwork/java/codeconventions-135099.html) – Jose Gómez Oct 26 '15 at 20:11
7

Underscores look ugly in package names. For what it's worth, in case of names compound of three or more words, I use initials (for example: com.company.app.ingresoegresofijo (ingreso/egreso fijo) -> com.company.app.iefijo) and then document the package purpose in package-info.java.

Pang
  • 9,564
  • 146
  • 81
  • 122
jpangamarca
  • 713
  • 2
  • 13
  • 33
  • 4
    this might not be readable and difficult to understand the contents of package by just looking at the package name – Vishal Akkalkote Feb 21 '19 at 05:56
  • 2
    Fair enough. That's why I suggest using documentation. I'd use this approach any time instead of full words concatenated (apiratesheet - is that 'API Rate Sheet' or 'A Pirate Sheet'?) – jpangamarca Feb 27 '19 at 15:56
  • 1
    it is just your flavor. i have two services with names like poirot_a, poirot_b. i don't like package poriot.a, casuse smb may want to place stuff into poirot package which may have no sense. – Simon Logic Mar 04 '22 at 08:50
2

Concatenation of words in the package name is something most developers don't do.

You can use something like.

com.stackoverflow.mypackage

Refer JLS Name Declaration

CraUmm
  • 101
  • 1
  • 4