Java in a Nutshell, 8th 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 grouped into the module. One recommended way to do this is to group the packages within a module and use the root name of the packages as the module name. For example, if an application’s packages all live under com.mycompany.*, then com.mycompany is a good name for your module.

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., ...