Whooo, Javadoc

[afuna]

The one thing I love about JavaDoc is that it starts with two stars. Makes it look special (and, in Eclipse, blue).

The things I don't like about JavaDoc are too many to count! But the list includes annotations! Why are you letting comments define behavior? That's just freaky.

On the flip side, documentation is a good warm up to the day, so!

Comments

Annotations

[allen]

Annotations aren't really part of JavaDoc. They just look like it.

I really disliked annotations until I started using them with the new Java Persistence API (and Stripes). Now I love them. It's really nice to write

@Entity
@Table(name="organization")
public class Organization extends NamedBean  {

  @Id
  @GeneratedValue
  @Column(name="organization_id")
  private long organizationId;
  ...

and have all of the DB mapping code just handled there, rather than having to write separate Hibernate XML files.

Now if only there were a standard way to autogenerate accessor methods...

[owl]

Hmm, I've just realised that I think of JavaDoc comments in a slightly different way than I do about normal comments, that they're more codey or something. I'm sure our tech lead would be glad to hear that, as he tears into JavaDoc with the same persistence as he does into code, but a block comment will only get an eyeroll unless it's on a whitaker's-mom level.

Re: Annotations

[afuna]

Oh true. I don't mind them as much when they're in that format, oddly. It's when they're in a comment, that they're annoying

(I was only editing a comment, so I didn't think to rebuild/retest the project before committing a patch. Turns out I'd deleted one line in the comment which actually had an effect on the code.

ARGH)

And +1 to autogenerate accessor methods. Objective-C and Ruby have spoiled me in that regard.

[afuna]

*snickers*

I do kinda see the point, though. Once processed, the JavaDocs are visible to even non-coder folks. Normal comments aren't visible in the same way.

[owl]

Yes, that is his point. However, in the middle of the code review he said thoughtfully, "You know, we really should generate this JavaDoc one of these days..." :D

[afuna]

*dies*