Forward from IBM Web Site to prepare Java member function documents
English original
Importance of Patent Terminal Scott W. Ambler, Ronin International, August 17, 2000
Try these suggestions for the content to be included when the Java member function documentation is prepared.
Each Java member function should perform documentation topping the top of the source code to include some kind of head, called a member function document. This information includes, but is not limited to, the following recommendations. Things doing the member function and the reason why this reason is to prepare a document through things to the member function, others can make it easier to determine if they can reuse your code. This document makes others more easily put your code into the context. It is also possible to make others more easily determine whether there should be a new change in their code (perhaps the reason why the new change is to conflict with the reason for the code). Which member functions must be passed as a parameter you also need to represent any parameters that will use the member function. This information allows other programmers to know what is transmitted to a member function. Javadoc @Param tag is used for this purpose. The member function returns what you need to prepare a document (if any) to the member function (if any), so that other programmers can use the return value or object correctly. @return tag for this purpose. Known errors should prepare documents for any unresolved issues of member functions so that other developers understand the shortcomings and difficulties of member functions. If a particular error can be applied to multiple member functions in a class, you should compile documents for this class rather than separately. Any exception brought by the member function You should have a document that throws you with a member function so that other programmers know what their code will need to catch something. Javadoc @Exception or @THROWS tag is used here. Visibility Decision If you think that other developers will doubt the visibility selected by the member function - prior to calling the member function in other objects - you should prepare your decisions Documentation. This will make other developers know your thoughts so that they will not take time to think about your operation. The member function changes the object if the member function changes the object, this needs to be pointed out. For example, the WITHDRAW () member function of the bank account modifies the account balance. This information allows other Java programmers to know how the member function call will affect the target object. How to call the member function in the appropriate time to determine one of the easiest ways of working how the code works is to look at the example, so it is very useful for one or two examples of how to call the member function. Applicable prerequisites and back conditions prerequisites are constraints that the member function is operated correctly, while the post-condition is true or assertion after the member function is running, (see the object-oriented software construction in the reference). By using a number of ways, prerequisites, and post-conditionation describes the assumptions when writing member functions and how to use a member function (see the Building Object Applications That Work in the reference). All concurrency issues For many developers, concurrency is a new and complex concept, and for most experienced concurrent programmers, it is just an old and complex topic. The final result is that if the concurrent programming characteristics of the Java programming language, they need to thoroughly prepare documents. Doug LEA (see Concurrent Programming in Java) suggests that when classes include synchronous and non-synchronous member functions, especially when it requires free access to allow other developers to securely use these member functions, they must Write the execution context-based documentation dependent on the member function. If the SETTER (update field of the update field) that implements the Runnable interface is not synchronized, the reason should be written. Finally, if you override or overload the member function and change its synchronization, it should also be written.
Document Example Figure 1 depicts a document example of a Java member function header. Please note how I applied standard Javadoc tags (such as @return) and non-standard Javadoc tags (such as @PRecondition). To support these new tags, I will need to develop DOCLETs or procurements that can be customized to identify their Java development tools. Figure 1. Member function head document example / **
WITHDRAW The Funds from this Account.
@Param Amount The Amount of the withdrawal.
@Return The Amount withDrawn.
@PRECondition the account must harve the bunds available for the
WITHDRAWN.
@Postcondition if The Funds Are Available The Will Be withdrawn and a record
Of the withdrawal will be name.
@throws insufficientfundsexception an in Indication That The Account Balance and
Overdraft limit.
@Modifies Yes Debits The Funds and Posts a Record Into The Account Transaction
History.
@Concurrency Changes To An Account Balance, Such As a withdrawal, Must Occur
AS an Acid Transaction.
* /
Important things are that you should write documents to you only when you make the code clearer. For each member function, documents will not be prepared for all elements described above because all elements can be applied to each member function. However, a document will be prepared for some of the elements of each member function you have written. Reference information For more information on logging Java member functions, see:
Building Object Applications That Work: Your Step-by-Step Handbook for Developing Robust Systems with Object Technology, by Scott Ambler. The Object Primer 2nd Edition, by Scott Ambler. Concurrent Programming In Java: Design Principles and patterns, Doug Lea Object-Oriented Software Construction, Second Edition
