documentation. Doc comments require write access to the source, and technical writers often do not have
permission to modify source code. The use of doc comments will require a change in such organizations.

Another issue is comment skew, in which comments become out of date as the source code changes over time.
You can reduce this problem by putting only contractual information in your doc comments and not
describing the implementation. When the implementation changes, the doc comment will still be correct as
long as the contract remains unmodified. Changing the contract of an existing type, constructor, method, or
field is a questionable practice in many cases, so such changes should be rare. Describing only the contract is
generally a good practice in any case because it frees you to change details of the implementation in the
future. Implementation details of methods need to be documenteduse regular comments for this purpose.

You can further reduce the problem of comment skew by defining a standard marker for programmers to
place in doc comments that need attention. For example, if you add a new method to a class, you could write
the first draft of the doccomment, but flag the comment as one that might need review and rework by the
documentation team:

/**

• ...initial draft...


• @docissue Review -- programmer's first draft
  */

A script run over the source could find @docissue markers and show them to the documentation team,
alerting them to work that remains to be done. Some documentation generators allow you to add your own
doc comment paragraph tags, so using an @ tagsuch as @docissue shown aboveallows you to flag these or
other issues directly in the generated documentation as well as in the source itself.

The universe is made of stories, not atoms.

Muriel Rukeyser

Chapter 20. The I/O Package

From a programmer's point of view, the user is a peripheral that types when you issue a read

request.

Peter Williams

The Java platform includes a number of packages that are concerned with the movement of data into and out
of programs. These packages differ in the kinds of abstractions they provide for dealing with I/O
(input/output).

The java.io package defines I/O in terms of streams. Streams are ordered sequences of data that have a
source (input streams) or destination (output streams). The I/O classes isolate programmers from the specific
details of the underlying operating system, while enabling access to system resources through files and other
means. Most stream types (such as those dealing with files) support the methods of some basic interfaces and
abstract classes, with few (if any) additions. The best way to understand the I/O package is to start with the
basic interfaces and abstract classes.

The java.nio package and its subpackages define I/O in terms of buffers and channels. Buffers are data
stores (similar to arrays) that can be read from or written to. Channels represent connections to entities
capable of performing I/O operations, including buffers, files, and sockets. The "n" in nio is commonly
understood as meaning "new" (the nio package predates the original stream-based io package), but it