Rule Definition
There is no dispute that these comments contribute to a developer's understanding and help a developer write reliable applications more quickly. Without documenting parameters it is dififcult for anyone else than the author to guess the purpose of the parameter except by looking at the code that is using it.
Remediation
Add a @param with a description for each method parameters.
Violation Code Sample
public Image getImage(URL url, String name) { //Violation try { return getImage(new URL(url, name)); } catch (MalformedURLException e) { return null; } }
Fixed Code Sample
/** * @param url an absolute URL giving the base location of the image * @param name the location of the image, relative to the url argument * @return the image at the specified URL * @see Image */ public Image getImage(URL url, String name) { try { return getImage(new URL(url, name)); } catch (MalformedURLException e) { return null; } }
Reference
https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param
Related Technologies
JEE
Technical Criterion
Documentation - Automated Documentation
About CAST Appmarq
CAST Appmarq is by far the biggest repository of data about real IT systems. It's built on thousands of analyzed applications, made of 35 different technologies, by over 300 business organizations across major verticals. It provides IT Leaders with factual key analytics to let them know if their applications are on track.