7

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?

  • 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
  • 3
    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
  • @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 '18 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 '18 at 12:34
24

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

  • 7
    That last paragraph is good. +1 – n0pe 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
  • 3
    @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
  • I prefer to modify homicidal maniac mantra into "You always write code for the poor guy at 3am hopped up on caffeine that is trying to read it." Yes, I'm talking to you out there, Mr. "Use a 1000 independent threads just because you can." – tgm1024--Monica was mistreated Oct 27 '18 at 13:18
  • I am a Ruby developer taking on a Java project. I'm stunned at all the nonsensical self-describing comments. – Greenspud Coder Aug 16 at 20:01
7

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.

  • I've been given the option of choosing either method. – n0pe 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
5

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.

5

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.

  • 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
2

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.

2

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.

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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