The Java language adopts an integrated approach in accordance with the JavaDoc annotation. Javadoc tools can help build good API documents, but most Java API documents are very bad. Because it is part of the source code, the API's documentation preparation is ultimately falling to the engineer. In this article, Brian criticized the current state of Java document preparation practices, and provided some guidelines on how to write more useful Javadoc.
For most Java class libraries, Javadoc is the only document. Moreover, in addition to the commercial software components, many Java classes will not use JavaDoc. Although Javadoc is excellent as the API reference tool, it is a very bad way for understanding how the class library is organized and how to use it. Even with Javadoc, it usually only contains the most basic information about what is completed, and ignores the scope and scope, thread safety, lock behavior, front condition, and rear conditions, and back conditions. Important features such as invariant conditions or side effects.
Learning to Javadoc For many Java tools including most open source packages and most internal developments, the actual situation is: including Javadoc, almost all class libraries or components do not have a valid document. This means that developers have to learn tools from Javadoc, and we should consider our Javadoc according to this reality. I often joked: Now one of the most important skills that Java programmers need to use Google and Javadoc to "reverse engineering" for "reverse engineering" to prepare very bad APIs. This may be true, but it is not very funny.
Most Java packs have some "root" object, which is the first object that must be created before getting any other objects within the tool. In JNDI, the root object is Context, and in JMS and JDBC, it is Connection. If someone tells you that the basic object in JDBC is Connection, and how to get this object, then you are likely to find how to create and execute Statement from Javadoc to see how you can create and execute Statement, and how to generate STATEMENTs from Javadoc. . But how do you know that getting Connection is your first step? Javadoc organizes classes in the package in the package and organizes the method in the class. Unfortunately, there is no magical "start here" in javadoc to bring the reader to the logical start position of the browsing API.
The package description is closest to the "From here" marker is a package description, but it rarely uses effective use. If the file package.html is placed in a packet with the source code, the standard Doclet will put the contents of the generated package-summary.html file together in the package together. Unfortunately, the standard doclets of the HTML document we are familiar with are unable to find the package. If you click a package in the top left pane, this will generate a list of methods in the lower left pane, but will not produce a summary of the bag in the main pane - must click the package name in the lower left pane. View summary. But don't matter, after all, most packages do not have a package.
The package document is an excellent place to place the "start" document from here. This document is used to overview what the package is doing, the main summary is what is the javadoc from where to start the browsing package.
In addition to class documents, class-specific documents can also play an important role in helping users can completely understand new tools. Class documents must of course include this particular class, but should also describe how other classes in this class are associated, especially to identify any factory class associated with this class. For example, the Statement class document in the JDBC should be explained: Statement is obtained by the CreateStatement () method of the Connection class. This way, if a new user is accidentally entering the Statement page, then he will find that first he needs to get Connection. Applying this convention for each class quickly pointed out the root object to the user, the user can be worn. Because Javadoc is designed around the document around the specific class, there is usually no obvious location in Javadoc to place sample code used with several related classes. However, due to the documentation of a specific class or method, we lost the opportunity to discuss how to combine content. If there is a simple code example of some basic usage in the package document or class document, it will be very useful for many users. For example, the Connection class document can have a simple example. This example gets the connection, create a pre-compiling statement, execute the statement and iterates the result set. As a technique, this may not belong to the Connection page because it also describes other classes in the package. However, especially when combining techniques that reference the class-dependent classes dependent on the current class, the user can quickly find the way to obtain a simple practical example, regardless of the organization of the class.
Worse documents == bad code For most Java class libraries, except for commercial products sold as packaging components, there is no javadoc, or very bad. Due to the fact that for most packages, Javadoc is the only document we have, which basically means that we will fall into such a dilemma: except for the author, others can't use our code - If you don't pay a major "archaeological", you will at least do this.
Since the document is now part of the code, I think it is time to form a consensus in the software engineering community, this is, even if the code is excellent, if the document is very bad, it should be considered a difference, because it cannot be reused. The unit test is not good before, but it is only to receive the favor of many engineers recently. Like it, in order to improve the reliability and reusability of the software we produce, the API document must also become an integration of the development process. section.
Writing Javadoc is a form of code checking that a reasonable Javadoc will also generate side effects. It forces us to conduct some form of code check to study the architecture of the class and the relationship between them. If a single package, class or method is difficult to prepare a document, then you can try to make documentation for multiple packets, classes, or methods at the same time, which should be a prompt, that is, it may be redesigned.
The self-inspection of the document makes certain aspects more important, that is, write Javadoc as soon as possible, and then check it as soon as the code is developed, not only waiting for the code to complete the document (if there is any remaining time ). The latter strategy is very common, it will write a document to the project, and when the time schedule is very tense, the developer's pressure is very large. The result is more common, it is a document that is not worthless in Figure 1, which only provides "document illusion". The user truly needs to understand the working principle of this class, and the document does not provide any such information.
Listing 1. Typical one-sheet Javadoc
/ **
* Repesents a command history
* /
Public class commandhistory {
/ **
* Get The Command History for a Given User
* /
Public static commandhistory getcommandhistory (String user) {
.
}
}
What is the so good documentation? The organizational techniques described above (references related classes or factory classes are referenced in class description, including package outlines and code samples) are good starts to form an excellent document. It helps new users use Javadoc to learn about new tools.
But the outline of the architecture completes half of the task. The other half is explained in detail what is doing and not doing, and runs under what conditions and how they handle the wrong condition. Most javadoc do not fully provide the information needed, even those who fully describe the behavior of the method in the expected behavior, these lack of information include:
Method How to deal with error conditions or unqualified input how to transfer the error condition to the caller to thistle to input is a valid class constant condition, method pre-condition or method Side effects have important coupons between the methods to handle multiple threads simultaneously access one instance.
Javadoc conventions provide @Param tags that allow us to develop documents to its meaning except for the name and type of parameters. However, not all methods can accept any value of parameters. For example, although a null value (NULL) can be legally transmitted without violating the type inspection rules, it is not all methods working properly when it is incurred. Javadoc should explicitly describe the valid parameter range, if it wants a parameter non-null, then it should be described, and if it expects the parameter value within a certain range, such as a certain length string or greater than 0 integers Then it should also be described. Not all methods have carefully examined the validity of its parameters; not performing validity checks, there is no document on acceptable input ranges, which combines the combination of these binds to the disaster.
Returns the code javadoc makes the meaning of the returning value become easier, but just like the method parameters, the @ RetURN tag should include a detailed description of the range of values that may be returned. Is it a null value for the return type of the object to the value? For the return type of integers, is the resulting limit on a collection of known values or non-negative values? Any return code has special meaning, for example from java.io.inputstream.read () returns -1 indicates file ending characters? Returning code will be used to indicate, for example, if you cannot find an entry, return an empty value?
The throws clause of the exception standard doclet replication method, but the javadoc @throws tag should be more specific. For example, NosuchFireException is a subclass of IOException, but most of Java.IO is only declared as throwing IOException. However, the method may throw NosuchFileException independently of other oException, which is a very useful fact that the caller to understand - it should be included in Javadoc. It should also be pointed out to throw a variety of exception classes, so that the caller knows what corrective actions should be taken when a given exception is thrown. You should use the @THROWS tag to prepare documents that may be thrown by the method, and the documentation is prepared for the throwing exception.
Of course, you should have a document on the method of object status. But you may need to prepare more detailed, pre-conditions, rear conditions, and clasped conditions of the method. The front condition is a constraint for the object state before the call method; for example, the pre-condition for calling item.next () is HASMORE () as true. The rear condition is the constraint of the object state after the method call is completed, for example after the add () is called. The constant condition is a constraint for the status of the object, which ensures that this state is always true, such as Collection.Size () == Collection.toArray (). Length (). The Design-By-Contract tool such as JCONTRACT allows you to specify the pre-condition, the rear condition, and class constant condition, then generate additional code to force these constraints. Whether you use tools to force these expectations, you can make users know what they want to use them safely, what they can do.
Side effects sometimes, in addition to changing the object state, there will be other side effects, such as changing the status of related objects, JVM, or underlying computing platforms. For example, all methods of performing I / O have side effects. Some side effects are harmless, such as reserving the number of requests for the request. Other side effects will have a major impact on the program performance and correctness, such as modifying the status of the object passed to the method, or stores a copy of the reference to the object. Side effects such as modifying the state of the related objects or storing the reference to the objects transmitted as the method parameters should be programmed.
Method coupling method connection means that two methods in the class are interdependent, and they have assumed the behavior of the other party. One common situation in which the method is coupled is: the method is internally using the same class totring method, and assumes toString will format the object state in a special method. If the class has been submitted and the toString method is rewritten, then this situation may cause problems; another method suddenly does not work properly unless it is also rewritten. If your method relies on the implementation behavior of other methods, you need to prepare documents for those dependence. Moreover, if the class has been subclassified, the two methods can be rewritten in a consistent manner to make the subclass still work normally.
One of the most important behaviors of thread safety should be programmed is thread security, and it is almost never preparing a document. Is this class a thread safe? If not, can it be safe to use with a synchronous package to secure? These synchronization must be associated with a specific pipeline or any useful management can be used? How did the method get a lock that is visible outside the class?
Thread security is actually not binary properties; thread safety has several identifiable levels. It is not always easy to make a document, or even determining thread security. But failure to do this will result in serious problems; use non-threaded security classes in concurrent applications that may cause sporadic failures, which often appear until the deployment (exposed the application to load). Moreover, additional lock packages will affect performance, even cause dead locks.
Josh Bloch provides a useful classification method in his Effective Java Programming Language Guide (see). Categories can be classified into the following groups in order of thread safety decline: non-variable, thread security, conditional thread security, thread compatibility, and thread alignment.
This classification is an excellent framework for passing important information about class behavior in concurrent access. No matter if you use this classification method, you should identify the thread security level displayed by your class. I also suggest: If the method gets the lock to an object, and the object is visible to the class itself, then you should also prepare a document, even if it is just a "implementation details", so that it can help make global lock sequences (Global-Lock-Order) decision-making and prevents deadlock. Conclusion The behavior of the class is far less than what to do for each method. Effective javadoc should include descriptions for the following:
How to interconnect how to affect the status method of the object How to notify them to inform them of the caller and how they may notify what error classes handle the use of how to use the usage method in multi-threaded applications and their return values
In addition, bad documents (or even worse, no documents) can cause excellent code to be unavailable or not reuse. By spend some extra time on the document, you will avoid countless setbacks for your users (maybe yourself).
