When copy/pasting private methods is it necessary to carry along the Javadoc? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 6 years ago.

Improve this question

So, unfortunately, I'm stuck with code where I'm doing this:

@Override
method A{
    //calls private methods 1-8
}

private method 1{
    //copy/pasted
}

And so on for all of the private methods. I'd have preferred if the developers of the method I'm overriding had made the private methods protected, but I can't change that now.

All of these private methods have javadoc along with them - should I carry this along with the copy/pasted functions in my class and adjust them accordingly, or not waste my time since it is documented in the original file?

Answer 1

I would recommend copying the javadoc along with the methods, since anyone looking at this class in the future may very well have no idea that these private methods are really the exact same as those in the originating class.

Also, when the javadoc for the new class is generated, those methods will not have their intended documentation. Plus, what if the implementation in either the original or the copied methods changes independently? It would be very easy for the javadoc to become out of sync.

Finally, since you are simply copying the methods wholesale, it's not really a waste of time to copy the adjacent documentation at the same time.

Answer 2

Could you, instead of copy pasting, just patch the code across as part of your build? If you marked up the start and end of the copied section in a particular comment style and then had a script pull that into your other file ahead of compilation you would have the same outcome but with an automated process.

That is obviously a terrible solution in general, but compared with copy pasting you are at least not having the same code squirrelled away in multiple places, which is almost guaranteed to cause you problems in future.

Also think very hard about whether there isn't some way you could avoid this altogether by thinking laterally about it. It may not be possible, but sometimes a smart solution will present itself.

Answer 3

For questions like this, I start by answering the question "what makes the code easier to understand for me and my organization?". That's by far the most important consideration.

Answer 4

Just as one does not copy and paste all of the methods from the superclass when writing code, so to should one not copy and paste all of the documentation when documenting overridden methods.

From javadoc at docs.oracle.com:

{@inheritDoc}

Inherits (copies) documentation from the "nearest" inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text.

This tag is valid only in these places in a doc comment:

• In the main description block of a method. In this case, the main description is copied from a class or interface up the hierarchy.
• In the text arguments of the @return, @param and @throws tags of a method. In this case, the tag text is copied from the corresponding tag up the hierarchy.

See Automatic Copying of Method Comments for a more precise description of how comments are found in the inheritance hierarchy. Note that if this tag is missing, the comment is or is not automatically inherited according to rules described in that section.

And thus, you inherit the documentation from the superclass. If the superclass documentation updates, yours does too.

Just as with inheritance of code, you can extend the comments.

Lets see what things look like in an IDE and code...

public interface IFace {
    /**
     * This is a method.
     */
    public void method1();

    /**
     * This is also a method
     */
    public void method2();
}

This is just an interface with some javadocs and two methods.

Lets have a class implement this...

public class CClass implements IFace {

    /**
     * {@inheritDoc}
     * This just returns.
     */
    public void method1() {
    }

    public void method2() {
    }
}

And then the javadocs themselves:

public void method1()
This is a method. This just returns.
Specified by:
method1 in interface IFace

img

public void method2()
Description copied from interface: IFace This is also a method
Specified by:
method2 in interface IFace

img

The first thing to see is that with method1, the javadoc is included and extended with the {@inheritdoc}. However, no javadoc will also inherit the javadoc from wherever.

If you are not changing the javadoc, don't specify it. Let the IDE do its thing. Let the automatic javadoc generation do its thing too. Copying and pasting documentation can be just as bad as copying and pasting code as it violates DRY and may lead to the documentation from the superclass or interface getting out of sync with the documentation of the method.

On the other hand, if you are going to write something more, inherit the documentation and write it.