0

I've just learnt about, and am now trying to implement javadocs.

Is there a way to re-use a javadoc which you have already written, say for example when you overload a method to take more parameters?

I ask because I have done exactly this: I wrote a method which took 7 parameters:

/** 
 * @param a    explanation a
 * @param b    explanation b
 * @param c    explanation c
 * @param d    explanation d
 * @param e    explanation e
 * @param f    explanation f
 * @param g    explanation g
 */
public void myMethod(int a, int b, int c, int d, int e, int f, int g)
{
    //Whatever
}

Then I added and overloaded version which accepted all the same parameters, plus an additional 3 (for a total of 10 parameters). 

/** 
 * @param a    explanation a
 * @param b    explanation b
 * @param c    explanation c
 * @param d    explanation d
 * @param e    explanation e
 * @param f    explanation f
 * @param g    explanation g
 * @param h    explanation h
 * @param i    explanation i
 * @param j    explanation j
 */
public void myMethod(int a, int b, int c, int d, int e, int f, int g, int h, int i, int j)
{
    //Whatever
}

I copied and pasted the existing javadoc from the 7-parameter version for the overloaded 10-parameter version, and elaborated on it.

It takes up a huge amount of space, and I can't help but feel like I'm missing something.

I have looked at the Oracle documentation, but if it is in there, I haven't spotted it yet.

I am aware that there are ways to reference variables in the javadoc with techniques such as {@code someparam}, so I think it is reasonable to assume that there may be a way to do this.

In my head I have a vision of something like: 

/** 
 * {@docstring theOtherVersionOfThisMethod}
 * @param h    explanation h
 * @param i    explanation i
 * @param j    explanation j
 */
public void myMethod(int a, int b, int c, int d, int e, int f, int g, int h, int i, int j)
{
    //Whatever
}
Jake Stokes
  • 445
  • 1
  • 5
  • 17
  • 2
    When a method has more than 3 parameters, it is usually a sign that the method is trying to do too much and should be broken into smaller methods. Breaking the code into smaller methods has the side effect that the parameters will be repeated in fewer places. – Code-Apprentice Sep 03 '17 at 17:01
  • **Single responsibility principle**. Clean code advocates go crazy when you use 3 or more parameters. 7 or 10 is way beyond that. That number is in realms, that when I would name them would get me another hint from the moderators to be nice and polite. So yes, documenting things is great. But sorry, but it doesn't help when you use it on code that has *such* problems. – GhostCat Sep 03 '17 at 17:06
  • @Code-Apprentice Thanks for the advice. The actual use case where I encountered this was creating two object constructors which accept parameters corresponding to columns in a database. There are 10 columns, the 7 parameter version sets defaults for the other 3. Is that okay? – Jake Stokes Sep 03 '17 at 17:08
  • @GhostCat Please see above - always appreciate advice. – Jake Stokes Sep 03 '17 at 17:10
  • 2
    @JakeStokes Hint: just because a table has 10 columns - doesn't mean that you have to use **one** class with 10 fields to represent that information. Your OO model should be written to be helpful to you. Your DB design should *not* drive your OO model! – GhostCat Sep 03 '17 at 17:10
  • @GhostCat thank you kind sir. Point noted. – Jake Stokes Sep 03 '17 at 17:16

0 Answers0