Java in a Nutshell, 6th 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 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, they should be followed carefully:

Packages

It is customary to try to ensure that your publicly visible package names are unique. One very 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). All package names should be lowercase.

Packages of code used internally by applications distributed in self-contained JAR files are not publicly visible and need not follow this convention. It is common in this case to use the application name as the package name or as a package prefix.

Reference types

A type name should begin with a capital letter and be written in mixed case (e.g., String). If a class name consists of more than one word, each word should begin with a capital letter (e.g., StringBuffer). If a type name, or one of the words of a type name, is an acronym, the acronym can be written in all capital letters ...