CODEWITHSUNDEEP
javaunit-testingjunitjavadoc
kerner1000
kerner1000

Reputation: 3546

Include link to (unit) test classes in JavaDoc

Is it, or should it be, good practice to include links to (unit) test classes in the JavaDoc of a class?

I have not seen this so far but find it very helpful when jumping between class and test class(es). I also think test cases give good examples for usage of a class.

What are the arguments against linking test cases in the JavaDoc?

Upvotes: 6

Views: 3023

Answers (1)

GhostCat
GhostCat

Reputation: 140427

Definitely not good practice.

For one simple reason: the responsibility of production code is to its "production job". Production code is not responsible for providing information about your test setup! Sometimes it is pragmatic to have a package-protected method around that allows you to inspect internal state of your object - to make unit testing easier. But that is something you do to make testing easier/possible. Meaning: such things can be acceptable (when not going overboard) - but this idea is not.

And even when you ignore that: the "standard" practice is to have your unit tests in a distinct, separate package. So, you got two projects prod with class/package "x.y.Z", and test with "x.y.ZTest". And: of course there should be only a dependency from test to prod - but not in the other direction. And "true linking" (like {@link SomeClass}) in javadoc would require you to have such a dependency. You can't link to a class that can't be resolved by the compiler in your project setup!

Beyond that: if you follow the above recommended layout for your projects, then you always know: "if there is a test for class Z - then this test should be named ZTest". And any decent idea finds ZTest for you.

In other words: when I want to look at a test for a class in eclipse, then I simply double click the class name (to select that name); then I press "ctrl-shift-t" (open type) ... and eclipse presents two classes to me: Z and ZTest.

Long story short: instead of polluting your production code with information that doesn't belong there - make sure you are following standard procedures and have the tools at hand that solve such problems for you. The reason why clean code is important: one has to understand that each line in source code represents costs. People who have to fix bugs or enhance functionality have to read that line (probably very often). Therefore: anything that doesn't support the core responsibilities of a class - should not be there.

Upvotes: 6

Related Questions