procedures to evolve Java Applications

Methods to Develop Java Applications

Methods to Develop Java Applications

Introduction

Principles

At Java Software, we have several guidelines that might make our documentation comments different than those of third party developers. Our documentation comments define the official Java Platform API Specification. To this end, our target audience is those who write Java compatibility tests, or conform or re-implement the Java platform, in addition to developers. We spend time and effort focused on specifying boundary conditions, argument ranges and corner cases rather than defining common programming terms, writing conceptual overviews, and including examples for developers.

Thus, there are commonly two different ways to write doc comments -- as API specifications, or as programming guide documentation. These two targets are described in the following sections. A staff with generous resources can afford to blend both into the same documentation (properly "chunked"); however, our priorities dictate that we give prime focus to writing API specifications in doc comments. This is why developers often need to turn to other documents, such as the J2SE Documentation, Java Tutorial or the Java Class Libraries (in hardback only) for programming guides.

Writing API Specifications

Ideally, the Java API Specification comprises all assertions required to do a clean-room implementation of the Java Platform for "write once, run anywhere" -- such that any Java applet or application will run the same on any implementation. This may include assertions in the doc comments plus those in any architectural and functional specifications (usually written in FrameMaker) or in any other document. This definition is a lofty goal and there is some practical limitation to how fully we can specify the API. The following are guiding principles we try to follow:

The Java Platform API Specification is defined by the documentation comments in the source code and any documents marked as specifications ...