0

I'm reading up about when it is necessary to provide @since and @version in the documentation of Java classes, however when is it appropriate to provide them? Was their original purpose for all visibility types or only public and/or protected?

I understand that the version is specific to the iteration of the function or member, and the since is relative to what version it was introduced, but is it the correct practice to add it to every member and function?

Examples:

/**
 * @version 1.2
 * @since 1.0
 */
public void myPublicMethod() {
    // this would be acceptable
}

/**
 * @version 2.1
 * @since 1.5
 */
private void myPrivateMethod() {
    // but would this?
}
jonrsharpe
  • 115,751
  • 26
  • 228
  • 437
  • 1
    Those attributes are used to help others understand the public API, there's no *need* to put them on anything private. That said, there's nothing preventing you from doing so if you or the rest of your team find it useful. – jonrsharpe Sep 09 '16 at 07:00
  • @jonrsharpe I'm assuming this counts for all protected fields aswell then. Does this mean the question is necessarily "primarily opinion based"? –  Sep 09 '16 at 07:04
  • Basically you're asking if it is good practice to use the tools available to you to document code. It may be less relevant for a generated javadoc you present to external parties, but that is not the only purpose of javadocs both generated an in-code. Its also for you. – Gimby Sep 09 '16 at 07:22

0 Answers0