|
I do a lot of Java programming at my work (I'm an intern) and I was wondering if it is generally a rule to create javadoc to accompany my code. I usually document every method and class anyways, but I find it hard to adhere to Javadoc's syntax (writing down the variables and the output so that the parser can generate html). I've looked at a lot of C programming and even C++ and I like the way they are commented. Is it wrong not to supply javadoc with my code? |
|||||||||||
|
|
In any writing, you write for your audience. Your audience is the maintenance developer, which may be you after 3 years after you have forgotten the details of how it all works. Single use throw away code, probably can be commented less. APIs to be consumed by other developers needs to be documented more. In no case does anyone need javadoc that only repeats the method signature (e.g. "This is a method with a return value of void and a name of HelloWorld and is invoked with no paramters") |
|||
|
This is generally a team/company decision; there is no right or wrong answer. It is also applicable to the type of software being developed; externally exposed and consumed versus internally exposed and consumed. With any comments; make them useful. Do not regurgitate the method signature. |
|||||
|
|
Javadoc is pretty much the accepted standard for documenting java code. Being able to convert it into HTML is just one of the benefits; a much more important one is that all the major Java IDEs understand it as well, and they will use it to display context-sensitive help while you code. If you don't adhere to javadoc syntax, this doesn't work and makes working with your code very annoying for people who are used to this convenience feature (and especially in the Java world, coding in an IDE rather than a simple text editor is the norm). In short, using your own commenting style is selfish, stubborn and childish. Learn javadoc. It's not that hard, and it might even be beneficial for your future career. |
|||
|
|
Yes. It's wrong not to create meaningful javadoc. It is wrong to write meaningless, uninformative boilerplate javadoc. |
||||
|
|
I would say it's wrong not to make certain that the code you develop is clearly and understandably documented for the situation at hand. What that means is situational. As an intern, consider that all the code you write is going to be someone else's responsibility. That ups the ante for what constitutes understandable documentation. As far as javadoc in particular, that is up to you and your employer, but you should definitely be sure that something gets left behind for another person to use. |
|||
|
|
|
If the problem is you find it hard to adhere to the javadoc syntax, a good IDE will help. For example, in Eclipse, open a comment with /** type an @ and the code completion feature will list the annotations available. Checking the result is as simple as hovering the mouse pointer over the method name. This also makes looking up the documentation really quick and easy without swapping to a web browser to view a documentation repository. |
|||
|
|
|
JavaDoc makes your code easier to use. I doubt it helps better than normal comments when it comes to bugfixing or modifying the code, but using your classes in other projects is by far easier and therefore more likely when JavaDoc comments allow other programmers to find and use your classes and methods. Since code reuse is generally better than reinventing the wheel, the omission of JavaDoc is hardly acceptable unless your code is so bad that reuse is not an option anyway. |
|||
|
|
