5

I know we have questions about comments in general but I'm specifically wondering about Java Doc style method documentation here.


I've been pruning unnecessary comments as I refactor and I've noticed our code has painfully obvious descriptions of methods.

/**
* @name save
* @desc Validates and saves submitted daily plant production information.
*/

Most of the "documented" functions are just method names used by convention in our MVC framework (CakePHP). It's inherently obvious that the save method in the Production Controller performs the necessary actions to save Production Information.

We don't actually use Java Doc and I question the value of these descriptions even if they were included in Java Doc style documentation. The only reason I haven't touched these because they're method documentation that's supposed to be valuable. The method documentation also hasn't been used consistently, about half of our Controller/model methods are documented.

Is there any reason to keep these obvious "Java Doc" comments or should I prune them in favor of "self documenting code" and only make Java Doc comments for less obvious methods?

2
  • 2
    Don't delete correct comments, even if they seem obvious to you. The next new guy you hire may well NOT find them obvious and that person will be grateful for these comments in strengthening their understanding of the framework. Feb 29, 2012 at 19:13
  • 4
    Given that the method is called "save" but the javadoc says "Validates and saves", I'd say the description isn't as painfully obvious as you suggest. If the method were called validateAndSave, I'd be more inclined to agree with you.
    – Kyralessa
    Feb 29, 2012 at 19:19

9 Answers 9

10

The point of javadocs is to provide information that isn't immediately obvious from just reading the method signature. Otherwise, it's just a waste of space. I disagree with the people who say that you shouldn't remove useless comments just for the sake of removing: those comments waste developer time, since the developers won't know that they're useless until after they read them. Go ahead and delete.

But an even better idea is to edit it so that it does provide useful information.

Before:

/** Sets the monkeyName field.
 * @param name - the monkey's name.
 */
public void setMonkeyName(String name) {

After:

/** Validates and stores the monkey's name per RFC 420, Monkey Enterprise Data Protocol.
 * 
 * @throws IllegalArgumentException if the name fails validation
 */
6

"Obvious" is "obviously" subjective.

I certainly wouldn't go removing "obvious" code comments just for the sake of it, or tidying things up (in your opinion).

It might be worth a dev team meeting to discuss the level comments need to be at from now on.

Going on a delete mission for the sake of it is liable to just annoy people.

2
  • 5
    No. Obvious is obvious. /* returnOne returns the value 1. */ int returnOne () { return 1; } Apr 4, 2012 at 20:24
  • 4
    /* ReturnOne returns the value of One. */ int ReturnOne() { return One.Instance.Value; } Jun 11, 2012 at 11:37
3

This is a very timely question to me, as in the legacy code I am working with, most of the Javadoc falls into this category. It is usually autogenerated, with either no useful information added by hand, or the info being out of date (or copied unmodified from another method's Javadoc).

The most annoying is the autogenerated Javadoc for trivial getters and setters on POD classes (we have lots of these). When I see a class having 50 or more fields, containing not much more than getters and setters for these fields, and the useless Javadoc taking up more than half of the screen real estate, I often end up removing it completely.

Javadoc for nontrivial methods is a different case. If it contains any useful info and/or it is for a public method, I prefer to keep it (and improve if possible).

0

Your question is should I prune them in favor of "self documenting code"

Ignoring the inevitable argument of their value, you shouldn't remove them if they are already there. If they are bothering you, change the code folding settings in your IDE.

You don't need to worry about having to edit in two places on a change (code/comments) as you would need to add Javadoc anyway if methods such as 'save' did anything that is not obvious in the method signature.

2
  • Part of the equation is I'm the only active developer on this project; I won't be ticking anyone off by removing the comments (the author no longer works here) but I don't want to harm the readability of our code to whoever else might work on the code in the future.
    – Ben Brocka
    Feb 29, 2012 at 15:03
  • Javadoc comments will not affect readability if you are using a tool with any basic level of sophistication. (Inline comments may)
    – smp7d
    Feb 29, 2012 at 15:06
0

I use this rule.

If the code itself is self documenting, then there is no need for these obvious comments. But during code review if the code reviewer feels it is difficult to understand the code in the first review, that means that the code needs some comments. I would go and add these comments.

Also if the code is impacted by internal features like thread safety / caching , it is better to add comments to the code indicating that

/* This code is not thread safe */ etc

0

Someone's obvious can turn out to be other person's mystery.

It depends on the context to know what is valuable or not :

An obvious thing may not be a good thing in some case: for example, * If the comment right a narration translation to code as is than there is really no value reading it.

However, sometimes you may answer

why is this method useful?

or better even -

"Don't supply NULL value - there is No ASSERT here" -

this would be obvious to someone who has written a code, but avoids great pit falls to someone reading first time.

The most common things that doesn't get commented because the developer things it is obvious - is the name and meaning of variables (or even methods sometimes) and almost always we find the peer developer snatching hair way too often.

0

This might be best answered in two parts:

General Case - If the project is going to be worked on by more than one person and the method documentation is going to be published in such a way that it can be read separate from the code itself (i.e. a website with Javadoc published), the method documentation should be in place and accurate since someone might go to the Javadoc first. When you are working on a project where there is an API involved this becomes even more important as you should not have to read the API's source code to determine if you can or cannot do something.

Specific Case - For the specific case you are provided, I'd likely clean them up and leave them in place if only so you can use the search capability of your IDE to find a method. In the example you provide above, unless all of the save methods in the program start by doing the validation, it really should be mentioned in the comment. If the validation is in another function that is being called by the save method then it could likely be stripped from the comment.

0

If this project is to have any longevity, you should keep the obvious documentation. It's obvious to you that a function called save "validates and saves", but I would have never guessed that save validates, since it's not called validateAndSave. As others have said, it's hard to define what is obvious; perhaps obviousness comes from conventions, such as "every save function validates." If someone comes from a different project with different conventions, you might end up with many similarly-named methods that fit into two categories. Then we have "Ben's save methods validate and save, and Don's save methods log to an audit mechanism and save."

Unless the method does exactly what it said and absolutely nothing else (apart from setters and getters, I think this is relatively rare), you need the documentation.

0

Redundant comments annoy the hell out of me too.

My advice would be to replace them with something better. Just deleting opens you up to missing something and deleting useful comments. If you are confident enough to recomment the method then you should understand it enough to prevent any pitfalls.

Is there any reason to keep these obvious "Java Doc" comments or should I prune them in favor of "self documenting code" and only make Java Doc comments for less obvious methods?

Your code should be self documenting and have comments. Since half your comments are not in Java Doc style I suggest you phase out Java Doc style comments. Consistency can be very useful with comments, there is no point implementing a style half the time.

Your Answer

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

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