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

Question

我正在为我的jsp web应用程序编写javadoc。 所以我有一个名为AcceptOrder的类（根据Command模式创建并位于服务层中）。 该类包含方法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并且我的命令方法执行的javadoc是否正确？ 在两种方法的描述中应该写什么。 似乎他们的描述是相同的 - 接受客户订单。

Answer 1

我认为你应该更好地解释方法在做什么，抛出异常的情况，返回的值，实际返回的内容以及原因。 如何调用此方法，示例。 您可以在课程级别解释常见用法，使用的依赖关系，一般工作流程，验证，建模。

Answer 2

我尝试遵循以下规则。

1. 您编写的代码是否为外部用户提供了API？ 或者它可能只是隐藏在另一个接口和类后面的内部实现（他们应该提供javadoc）？
2. 当您编写文档时，请考虑您希望从您不知道的API中看到的内容
3. 不要写明显的东西（例如getter和setter的简单javadoc，不要只重复没有空格的方法名等）
4. 可能您不应该共享实现细节，因为它对您的API用户来说无关紧要。 但是，有时您需要共享一些细节以警告用户，以免他们滥用您的API。 如果您需要为将来的代码维护者留言，请将其留在代码注释中，而不是公共javadoc
5. 记录null处理。 它被接受为参数值吗？ 如果是的话，它有什么意义？ 该方法可以返回null吗？ 如果是，在什么情况下？
6. 记录例外。 为API客户端提供有用的信息，以便他们能够妥善处理它们。
7. 记录关于阶级状态的任何假设。 对象是否需要处于特定状态才能调用该方法，否则会引发异常？
8. 继承：是为扩展而设计的类（否则它应该标记为final ，right）？ 如果是，子类是否应遵守任何特定规则？
9. 线程安全：类线程安全吗？ 如果该类是为扩展而设计的，那么子类应如何保护线程安全？
10. 根据您的域，性能可能非常重要。 也许你需要记录时间和空间的复杂性。

再一次，总是试着想一想你对外部库有什么样的信息。 我经常使用Java SDK和Java EE javadoc。 它的某些部分很棒。 从其他人那里我会期待信息，比如我是否可以使用来自多个线程的对象，但是没有关于它的单词，我必须引用来源（并且永远不能保证我的发现是正确的）。

另一方面，也要考虑是否应该写一个javadoc注释。 这值得么？ 您是否拥有API的外部客户端（特别是无法访问您的源代码）？ 如果你这样做，你可能也应该写一本参考手册 。 如果你有一个小应用程序和一个小团队，可能更容易浏览短方法体。

请注意，我并不是说你根本不应该写javadoc。 我想说javadoc是一个具有特定目的的工具。 想一想，如果编写一个特定的javadoc片段将帮助您实现它。