javadoc for service and DAO layer classes with same targets

Question

I'm writing javadoc for my jsp web application. So i have a class (created according to Command pattern and located in service layer) called AcceptOrder. This class contains method execute and it calls method acceptOrder from DAO layer. Class is located in service layer.

/**

* Class allows customer order (which was assigned by dispatcher) be accepted      by driver.   
* 
*
*/


public class AcceptOrder implements Command {

private static final String USER_ATTRIBUTE = "user";
private static final String ORDER_ID_ATTRIBUTE = "order_id";
private static final String DAO_COMMAND_EXCEPTION_MESSAGE = "Exception on executing DAO command";
private static final String WRONG_ORDER_ID_EXCEPTION_MESSAGE = "Wrong order ID";
/** {@inheritDoc}
 * <p> Accepts user order, which was assigned by dispatcher. 
 * @param request request object
 * @param response response object
 */
@Override
public String execute(HttpServletRequest request, HttpServletResponse response) throws CommandException {
    DriverDao driverDao = MySqlDaoFactory.getInstance().getDriverDao();

    try {
        User user = (User) request.getSession().getAttribute(USER_ATTRIBUTE);
        int userId = user.getId();
        int orderId = Integer.valueOf(request.getParameter(ORDER_ID_ATTRIBUTE));
        driverDao.acceptOrder(orderId, userId);
    } catch (DaoException e) {
        throw new CommandException(DAO_COMMAND_EXCEPTION_MESSAGE, e);
    } catch (NumberFormatException e) {
        throw new CommandException(WRONG_ORDER_ID_EXCEPTION_MESSAGE, e);
    }
    return PageManager.getInstance().generatePageRequest(CommandName.SHOW_DRIVER_ORDER);
}

}

Aslo i have a method in driver DAO class (in DAO layer) called acceptOrder which connects to the database and apply some changes according to parameters.

@Override
    public void acceptOrder(int orderId, int userId) throws DaoException {
        ConnectionPool connectionPool = null;
        Connection connection = null;
        PreparedStatement preparedStatement = null;
        ResultSet result = null;
        try {
            connectionPool = ConnectionPool.getInstance();
            connection = connectionPool.takeConnection();
            preparedStatement = connection.prepareStatement(SQL_ACCEPT_ORDER);
            preparedStatement.setInt(1, userId);
            preparedStatement.setInt(2, orderId);
            preparedStatement.executeUpdate();
        } catch (SQLException e) {
            throw new DaoException(STATEMENT_EXCEPTION_MESSAGE, e);
        } catch (ConnectionPoolException e) {
            throw new DaoException(CONNECTION_POOL_EXCEPTION_MESSAGE, e);
        } finally {
            connectionPool.closeConnection(connection, preparedStatement, result);
        }
    }

So the question is : What javadoc should i write for it and is my javadoc for command method execute is correct? What should be written in the description of both methods. Seems like their descriptions are the same- accept customer order.

Answer 1

I think you should explain better what is the method doing, cases when exception is thrown, returned values, what is actually returned and why. How to call this method, examples. A common usage, dependencies used, general workflow, validation, modeling you can explain at the class level.

Answer 2

I try to follow the rules below.

1. Does the code you write provide an API for external users? Or maybe it's just an internal implementation hidden behind another interfaces and classes (and they should provide that javadoc)?
2. When you write the doc, think what you would like to see from the API you don't know
3. Don't write obvious things (eg trivial javadoc for getters and setters, don't just repeat method name without spaces etc.)
4. Probably you shouldn't share the implementation details as it shouldn't matter to the user of your API. However, sometimes there are some details that you need to share to warn users so they don't misuse your API. If you need to leave a message for future code maintainers leave it in the code comment, not public javadoc
5. Document null handling. Is it accepted as the parameter value? If yes, what meaning does it have? Can the method return null ? If yes, under what circumstances?
6. Document exceptions. Provide useful information for API clients so they can appropriately handle them.
7. Document any assumptions about the class state. Does the object need to be in a particular state in order to call the method because otherwise it will throw an exception?
8. Inheritance: is the class designed for extension (otherwise it should be marked final , right)? If yes, should subclasses obey any specific rules?
9. Thread safety: is the class thread safe? If the class is designed for extension, how subclasses should preserve thread safety?
10. Depending on your domain, performance might be very important. Maybe you need to document time and space complexity.

And again, always try to think what information you would expect from an external library. I use Java SDK and Java EE javadoc a lot. Some parts of it are great. From others I would expect information like if I can use an object from multiple threads or not but there is no single word about it and I have to refer to sources (and there will never be guarantee that my findings will be correct).

On the other hand think also if you should write a javadoc comment at all. Is it worth it? Will you have external clients of your API (especially without access to your source code)? If you do, you probably should also write a reference manual . If you have a small application and a small team, it might be easier to just skim the short method body.

Note that I am not saying you shouldn't write javadoc at all. I am trying to say that javadoc is a tool with a specific purpose. Think if writing a specific snippet of javadoc will help you to fulfill it.