Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
5  
Note that e.g. Eclipse has great support for showing javadoc of methods in hovers and panels allowing you to easily see documentation of just about anything. –  user1249 Jun 21 '11 at 18:07
2  
As an intern, I'd say the most important rules to follow are those of your workplace, written or unwritten. If others are using Javadoc style comments, you should, too. If others aren't, well, it's still not a bad idea to do so, but it's also less important to do so. –  Ben Hocking Jun 21 '11 at 18:26
    
I would go as far as saying that if your method/class requires JavaDoc, you should rethink naming/organization. One should aim to need as little documentation in code as possible. If you really need documentation, JavaDoc is the way to go, but always try to make code such that it is as self explanatory as possible. So definitely, no JavaDoc for everything, unless it's needed which then means that you've got really ugly piece of code in your hands. –  merryprankster Jul 22 '11 at 9:23

7 Answers 7

up vote 17 down vote accepted

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")

share|improve this answer
6  
That last paragraph is good. +1 –  maxmackie Jun 21 '11 at 18:10
    
Write javadoc as if the next guy to maintain your code is a homicidal maniac who knows where you live. (lightly paraphrased) –  Spoike Jun 23 '11 at 20:44
1  
@Spoike, OK, but is he a homicidal maniac who loves javadoc, or a homicidal maniac who hates javadoc? –  Steve314 Jul 22 '11 at 6:38

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.

share|improve this answer

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.

share|improve this answer

Is it wrong to not supply javadoc with my code?

Yes. It's wrong not to create meaningful javadoc.

It is wrong to write meaningless, uninformative boilerplate javadoc.

share|improve this answer
    
that suggests that it's better to write no javadoc than to write meaningless javadoc, which is probably right, but seems to contradict your initial "Yes". If your code is sufficiently self-descriptive, some things won't need javadoc - any that you do include will not add meaning (even in a summary sense), and will therefore be meaningless. Any comments are generally for "why" more than "how", but even the "why" is sometimes clear without them. –  Steve314 Jul 22 '11 at 7:57

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
    
I've been given the option of choosing either method. –  maxmackie Jun 21 '11 at 18:06
    
@MaxMackie That leads me to believe there is no predestined use for them; stick with standard comments. Doing more for unknown gain is pointless. If you can leverage an IDE as noted by Thorbjørn and doing them does not increase the effort; then no harm no foul. –  Aaron McIver Jun 21 '11 at 18:07

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.