11

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?

Improve this question
6
  • 6
    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, 2011 at 18:07
  • 4
    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, 2011 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, 2011 at 9:23
  • @merryprankster, I'm coming in late to this, but your first assertion goes somewhat too far. In my lifetime I've seen plenty of 100% understandable and otherwise elegantly and clearly written code that still benefits from documentation, javadoc or otherwise. I remember once someone from my distant past saying something similarly broken: "If your code needs comments, then redesign your code." That was a mistake as well.
    – tgm1024--Monica was mistreated
    Oct 27, 2018 at 13:09
  • @tgm1024 I think you are saying almost the same thing I was saying. Now that I read this again, maybe my last sentence is not exactly stating how I feel about this subject ("needed" should be "required"). I'm sure there are cases when this does not apply, but as a rule of thumb I still think that if understanding the meaning/intent of the method/class requires documentation, it would benefit from restructuring and/or renaming.
    – merryprankster
    Nov 6, 2018 at 12:34

7 Answers 7

Reset to default
31

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

Improve this answer
6
  • 11
    That last paragraph is good. +1
    – n0pe
    Jun 21, 2011 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, 2011 at 20:44
  • 3
    @Spoike, OK, but is he a homicidal maniac who loves javadoc, or a homicidal maniac who hates javadoc?
    – user8709
    Jul 22, 2011 at 6:38
  • 3
    I am a Ruby developer taking on a Java project. I'm stunned at all the nonsensical self-describing comments.
    – Greenspud Coder
    Aug 16, 2019 at 20:01
  • 1
    It is an absolute requirement of most shops quality systems to write meaningless JavaDoc. Every parameter needs to be individually documented, regardless of whether there is anything meaningful to say. The purpose of these documents is to meet coding standards, and I would like to see something that could automatically generate them. Any real comments go in // comments outside the javadoc, because nobody reads the javadoc unless they are really desperate and looking to be disappointed.
    – Tuntable
    Jan 20, 2022 at 1:11
9

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.

Improve this answer
2
  • I've been given the option of choosing either method.
    – n0pe
    Jun 21, 2011 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, 2011 at 18:07
8

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.

Improve this answer
8

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.

Improve this answer
1
  • 1
    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.
    – user8709
    Jul 22, 2011 at 7:57
3

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.

Improve this answer
3

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.

Improve this answer
0

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.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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