Java in a Nutshell, 7th Edition

Chapter 7. Programming and Documentation Conventions

This chapter explains a number of important and useful Java programming and documentation conventions. It covers:

• General naming and capitalization conventions

• Portability tips and conventions

• javadoc documentation comment syntax and conventions

Naming and Capitalization Conventions

The following widely adopted naming conventions apply to modules, packages, reference types, methods, fields, and constants in Java. Because these conventions are almost universally followed and because they affect the public API of the classes you define, you should adopt them as well:

Modules

As modules are the preferred unit of distribution for Java applications from Java 9 onward, you should take special care when naming them.

Module names must be globally unique—the modules system is essentially predicated on this assumption. As modules are effectively super-packages (or aggregates of packages) the module name should be closely related to the package names that are grouped into the module. One recommended way to do this is to group together the packages within a module, and use the root name of the packages as the module name.

Packages

It is customary to ensure that your publicly visible package names are unique. One common way of doing this is by prefixing them with the inverted name of an internet domain that you own (e.g., com.oreilly.javanutshell).

This convention is now followed less strictly than it used to be, with some projects ...