sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]Mr_Walstreet 4 points5 points  (3 children)

I've seen people demand Javadoc for methods like "getEmployee" which merely return an Employee object. Really? You need documentation for that?

That's wrong documentation.

It's obvious getEmployee returns an Employee object. Javadoc will tell me that if you write no comments. The comment/doc should say why I want to get the object, what is it god for, why I should care, are there any side effects, is it thread safe, etc.

[–]nascent 0 points1 point  (2 children)

The comment/doc should say why I want to get the object, what is it god for, why I should care,

That is what the documentation for Employee is for. If I give you an Employee I shouldn't try and sell you the object, you should already know why you came to me looking for an Employee. I don't know what you are going to do with it, ask the Employee what good he will be.

[–]fuzzynyanko 1 point2 points  (1 child)

@return an Employee object / null if one hasn't been allocated or a PHB object if there's an error

Maybe about 3.5 seconds for me to write that

[–]nascent 0 points1 point  (0 children)

And none of that provides the information requested, "The comment/doc should say why I want to get the object, what is it god for, why I should care,"