Programming and Problem Solving with Java

6.7 Packages | 299

Why is putting a class in a package and importing the package a better strat-
egy than putting the class in the same directory as the importing class? There are
two reasons. First, any number of compilation units can be put in a package and
imported with one statement. Second, a package can be imported from anywhere.
That is, a package is stored in a directory named after the package, so it can be im-
ported by any application, not just one in the same directory.

Documentation

As you create your object-oriented design, you are developing documentation for your code.

Documentationincludes the written problem specifications, design, development history, and

actual code.

Good documentation helps other programmers read and understand your code and can

prove invaluable when software is being debugged and modified (maintained). If you haven’t

looked at your code for six months and need to change it, you’ll be happy that you documented

it well. Of course, if someone else has to use and modify your program, good documentation is

indispensable.

Documentation is both external and internal to the code. External documentation includes

the specifications, the development history, and the design documents, such as CRC cards.

Internal documentation includes code formatting andself-documenting code—meaningful iden-

tifiers and comments. You can use the pseudocode from your design as comments in your

code.

This kind of documentation may be sufficient for someone reading or maintaining your ap-

plications. However, if an application will be used by people who are not programmers, you

must provide a user’s manual as well.

Be sure to keep your documentation up-to-date. Indicate any changes you make in the code

in all of the pertinent documentation. Use self-documenting code to make your programs more

readable.

Self-documenting code

Program code containing mean-

ingful identifiers as well as judi-

ciously used clarifying

comments