具有相同目标的服务和DAO层类的Javadoc

Question

我正在为我的JSP Web应用程序编写javadoc。因此，我有一个根据命令模式创建并位于服务层中的类，名为AcceptOrder。该类包含execute方法，并调用DAO层中的acceptOrder方法。该类位于服务层。

/**

* 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);
}

}

此外，我在驱动程序DAO类（在DAO层）中有一个名为acceptOrder的方法，它连接到数据库并根据参数应用一些更改。

@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);
        }
    }

所以问题是: 我应该为此编写什么javadoc，我的command方法执行的javadoc是否正确?这两种方法的描述应该写什么。似乎它们的描述是相同的-接受客户订单。

- Sergey K

Answer 1

我认为你应该更好地解释一下这个方法的作用，异常抛出的情况，返回值，实际返回的内容以及原因。如何调用此方法，例如。一个常见的用法，使用的依赖项，一般的工作流程，验证，建模可以在类级别上进行解释。

- Roman C

Answer 2

我试图遵循以下规则。

你编写的代码提供了外部用户的API吗？或者它只是一个隐藏在其他接口和类后面的内部实现（它们应该提供javadoc）？

当你编写文档时，请考虑一下你希望从未知API中看到什么。

不要写一些显而易见的东西（例如，对于getter和setter的琐碎的javadoc，请不要只是重复方法名称而没有空格等）。

可能不应该共享实现细节，因为这对API的使用者并不重要。然而，有时候有一些细节是你需要分享的，以便警告用户，以免滥用您的API。如果您需要给未来的代码维护人员留言，请在代码注释中留下。

记录对null处理。他能作为参数值被接受吗？如果是，请问它有什么含义？方法是否可以返回null？如果是，在什么情况下会返回null？

记录异常。为API客户端提供有用的信息，以便他们可以适当地处理异常。

记录关于类状态的任何假设。对象需要处于特定状态才能调用方法吗？否则会抛出异常吗？

继承：类是否设计用于扩展（否则应该标记为final，对吗）？如果是，子类应该遵守任何特定规则吗？

线程安全性：类是否线程安全？如果类设计用于扩展，子类应该如何保持线程安全？

根据你的领域，性能可能非常重要。也许您需要记录时间和空间复杂度。

再次提醒，总是尝试思考从外部库中需要哪些信息。我经常使用Java SDK和Java EE javadoc。其中一些部分很好，但有些部分的信息我期望能够得到，例如我是否可以在多个线程中使用一个对象，但是没有任何单词提及，我必须参考来源（并且我的发现永远不会保证正确）。

另一方面，请考虑是否应该编写javadoc注释。它值得吗？你是否拥有API的外部客户端（特别是没有访问源代码的客户端）？如果有，你可能还应该编写参考手册。如果你有一个小型应用程序和小团队，只需浏览简短的方法主体可能更容易。

请注意，我并不是说你根本不应该编写javadoc。我试图说javadoc是一种具有特定目的的工具。请思考编写特定片段的javadoc是否有助于实现它。

- Piotrek Bzdyl