Tuesday, March 2, 2010

Useless Javadoc

Javadoc, similarly to comments , is useless in a in-house project (with no public API), and would show that the class/method is not named properly, or do more stuff that it is supposed to do.
Moreover when it is automatically generated by the IDE ( namely Eclipse),  you might see horrors like that :

     * @param bookId
     * @param bookType
     * @return Book
     * @throws Exception
     */
    public Book geBook(String bookId, Long bookType) throws Exception
Great. Very useful. In that particular case, I'd rather not have any Javadoc since the method is pretty straightforward, and I don't know what kind of exception I would get.
Some argue that Javadoc  could be useful for boundary cases.
" What the method would do if there is no book type with a given type ID ?"
Well return  a typed exception BookTypeNotFoundException and I am sure that you would not need any Javadoc.

No comments: