Do not use JAVA doc in your page classes
Many page classes use JavaDoc to explain how the methods work.
For example:
/**
* Method to navigate to a tab
*
* @tabName - the name of the tab to navigate to
*/
public void navigateToTab(String tabName) {
String locator = String.format("//a[@title='%s']", tabName);
By by = By.xpath(locator);
driver.findElement(by).click();
}
/**
* Gets the user name from the properties
*
* @param fileName - name of the property file that stores the user credentials
* @return - user name value
*/
public String getUserName(String fileName) {
Properties properties = new Properties();
properties.load(propertyFileName);
return properties.getProperty("username"));
}
/**
* This method gets the name of a url parameter
*
* @param index - index of the parameter
* @return - name of the parameter
*/
public String getParameterNameFromUrl(int index) {
String url = driver.getCurrentUrl();
String[] parameters = url.split("&");
String parameter = parameters[index];
int i = parameter.indexOf("=");
return parameter.substring(0, i);
}
/**
* This method gets the value of a url parameter
*
* @param index - index of the parameter
* @return - value of the parameter
*/
public String getParameterValueFromUrl(int index) {
String url = driver.getCurrentUrl();
String[] parameters = url.split("&");
String parameter = parameters[index];
int i = parameter.indexOf("=");
return parameter.substring(i + 1);
}
/**
* Method to verify if an element is displayed
*
* @param locator - locator of the element
* @return boolean
*/
public boolean verifyElementIsDisplayed(String locator) {
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(timeout));
try {
wait.until(ExpectedConditions
.visibilityOfElementLocated(By.xpath(locator)));
return true;
}
catch (Exception e) {
return false;
}
}You could say that adding the JAVA doc is a good idea as we get a lot of details this way about the
method’s purpose
method’s parameters
method’s return value
author
I think the opposite.
All these JavaDoc are actually useless as they do not bring any value.
Each method is so simple that no one should have any problem understanding
what the method does
the method’s parameters
the method’s return value
The code of each method is short and simple, the method names are clear, the parameter names are clear as well.
So, we should not use any JavaDoc for these methods.
Wait a second, wait a second!!!
But what about this method?
/**
* Method to type keyword in search box and submit:
*
* - Waits for the search box to be visible.
* - Finds search box and types keyword in it.
* - Waits for the search button to be visible.
* - Finds search button and clicks it.
*
* @param key - keyword to the typed
* @return boolean
*/
public void typeKeywordAndSubmit(String key) {
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(timeout));
wait.until(ExpectedConditions
.visibilityOfElementLocated(By.xpath("//input[@title = 'search']"));
driver.findElement(By.xpath("//input[@title = 'search']")).sendKeys(key);
wait.until(ExpectedConditions
.elementToBeClickable(By.xpath("//button[@title = 'submit']")));
driver.findElement(By.xpath("//button[@title = 'submit']")).click();
}The code of this method is not trivial as it does so many things:
waiting for elements to be visible/clickable
finding elements
typing into elements
clicking elements
The JavaDoc is for sure helpful here.
Sorry to disappoint again, but no, it is not helpful at all.
The method can be refactored so that it is more clear:
public void search(String keyword) {
typeKeyword(keyword);
clickSearchButton();
}
private By searchButtonBy = By.xpath("//button[@title = 'submit']");
private void clickSearchButton() {
getWait(30).until(
ExpectedConditions.elementToBeClickable(searchButtonBy));
driver.findElement(searchButtonBy).click();
}
private By searchBoxBy = By.xpath("//input[@title = 'search']");
private void typeKeyword(String keyword) {
getWait(30).until(
ExpectedConditions.visibilityOfElementLocated(searchBoxBy));
driver.findElement(searchBoxBy).sendKeys(keyword);
}
private WebDriverWait getWait(int seconds) {
return new WebDriverWait(driver, Duration.ofSeconds(seconds));
}The original method does too many things so it was broken into multiple methods:
one for typing the keyword
one for clicking the search button
The new method is just 2 lines long, the additional methods being 3 lines long.
Their code is very simple so everyone should be able to understand it.
In conclusion, do not use JAVADOC for page methods.
Write short, easy to understand code instead.
If you like this site, you may like my Kindle ebooks as well.
Check them out using these links. Thanks.