AP Computer Science a Quiz: Documentation With Comments

public class Wallet { private double balance;

/**
 * Adds money to the wallet.
 * Precondition: amount > 0
 * Postcondition: balance is increased by amount.
 */
public void addMoney(double amount)
{
    balance = amount;
}
// ... constructor not shown

}

The implementation of the addMoney method is incorrect because it does not meet its postcondition. Why?

/**

• Sets the score for a student.
• Postcondition: The student's score is updated to newScore.
• @param newScore the student's new score */ public void setScore(int newScore) { int score = newScore; }

The setScore method is intended to update an instance variable named score. Why does this implementation fail to meet its documented postcondition?

/**

• Moves a player on a game board.
• Precondition: The player's current position is valid.
• @param numSpaces the number of spaces to move / public void movePlayer(int numSpaces) { / ... */ }

The precondition 'The player's current position is valid' is documented for the movePlayer method. Why is this statement considered a precondition?

/**

• Returns the first character of a given string.
• @param word a non-empty string
• @return the first character of word */ public char getFirstChar(String word) { return word.charAt(0); }

The documentation for getFirstChar states that word should be a non-empty string. Which of the following is an additional, unstated precondition required to prevent a run-time error?

/**

• Calculates the area of a rectangle.
• @param width the width of the rectangle
• @param height the height of the rectangle
• Precondition: width > 0 and height > 0
• @return the area of the rectangle / public double calculateArea(double width, double height) { / implementation not shown */ }

Consider the provided calculateArea method. Which of the following statements best describes a precondition for this method?

/**

• Replaces all occurrences of a target word with a replacement word.
• @param words The list of words to be processed.
• @param target The word to be replaced.
• @param replacement The word to substitute for the target.
• Postcondition: For every index i, if the original element at words.get(i)

•            was equal to target, the new element at words.get(i)
  

•            is equal to replacement.
  

/ public void replaceAll(ArrayList words, String target, String replacement) { / implementation not shown */ }

Based on the postcondition provided in the documentation, what is guaranteed to be true after a call to replaceAll?

A programmer is writing documentation for a method that sorts an ArrayList of String objects in alphabetical order.

public void sortStrings(ArrayList<String> list)

Which of the following would be an appropriate postcondition to include in the documentation for the sortStrings method?

In the StudentRecord code below, what information do the inline comments provide in this program?

import java.util.ArrayList;
import java.util.List;

/**
 * Maintains quiz scores and computes an average.
 * Demonstrates how inline comments can justify small design choices.
 */
public class StudentRecord {
    private final List<Integer> quizScores = new ArrayList<>();

    /**
     * Adds a quiz score from 0 to 10.
     *
     * @param score the quiz score
     * @return true if the score is stored
     */
    public boolean addQuizScore(int score) {
        if (score < 0 || score > 10) {
            // Enforce the stated scale so the average remains interpretable.
            return false;
        }
        quizScores.add(score);
        return true;
    }

    /**
     * Computes the arithmetic mean of stored quiz scores.
     *
     * @return the average, or 0.0 if no scores exist
     */
    public double averageScore() {
        if (quizScores.isEmpty()) {
            // Avoid dividing by zero when no scores have been added.
            return 0.0;
        }

        int sum = 0;
        for (int score : quizScores) {
            // Accumulate the total to compute the mean in one pass.
            sum += score;
        }
        return (double) sum / quizScores.size();
    }
}

In the LibraryManager code below, what is the purpose of the comments in the provided code snippet?

import java.util.HashSet;
import java.util.Set;

/**
 * Tracks a set of unique book titles for a small library catalog.
 * Comments illustrate why specific validations are performed.
 */
public class LibraryManager {
    private final Set<String> titles = new HashSet<>();

    /**
     * Adds a title to the catalog.
     *
     * @param title the title to add
     * @return true if the catalog changed
     */
    public boolean addBook(String title) {
        if (title == null) {
            // Null titles provide no searchable value.
            return false;
        }
        String normalized = title.trim();
        if (normalized.isEmpty()) {
            // Blank strings are rejected to avoid cluttering the catalog.
            return false;
        }
        return titles.add(normalized);
    }

    /**
     * Determines whether a title exists in the catalog.
     *
     * @param title the title to check
     * @return true if present; false otherwise
     */
    public boolean contains(String title) {
        if (title == null) {
            return false;
        }
        // Trim to treat leading/trailing spaces as insignificant.
        return titles.contains(title.trim());
    }
}

Refer to this StudentRecord code snippet: ```java import java.util.ArrayList; import java.util.List;

/**

• Maintains grades and computes a simple GPA. */ public class StudentRecord { private final List grades = new ArrayList<>();

  /**

  • Adds a grade to the record.
  • @param grade value from 0 to 100 */ public void addGrade(double grade) { // Clamp values to keep calculations within an expected range. double clamped = Math.min(100.0, Math.max(0.0, grade)); grades.add(clamped); }

  /**

  • Computes GPA on a 4.0 scale.

  • @return GPA, or 0.0 if no grades */ public double calculateGpa() { if (grades.isEmpty()) { return 0.0; }

    double sum = 0.0; for (double g : grades) { sum += g; }

    double average = sum / grades.size(); // Linear conversion keeps the example straightforward. return (average / 100.0) * 4.0; } }

In the SimpleCalculator code below, what information do the inline comments provide in this program?

/**
 * Performs basic arithmetic operations.
 * Emphasizes documentation with Javadoc and inline comments.
 */
public class SimpleCalculator {

    /**
     * Adds two numbers.
     *
     * @param a first operand
     * @param b second operand
     * @return the sum of a and b
     */
    public double add(double a, double b) {
        return a + b;
    }

    /**
     * Subtracts one number from another.
     *
     * @param a first operand
     * @param b second operand
     * @return the result of a minus b
     */
    public double subtract(double a, double b) {
        return a - b;
    }

    /**
     * Multiplies two numbers.
     *
     * @param a first operand
     * @param b second operand
     * @return the product of a and b
     */
    public double multiply(double a, double b) {
        return a * b;
    }

    /**
     * Divides one number by another.
     *
     * @param numerator value to be divided
     * @param denominator value to divide by
     * @return the quotient
     * @throws IllegalArgumentException if denominator is zero
     */
    public double divide(double numerator, double denominator) {
        if (denominator == 0) {
            // Division by zero is undefined, so we fail fast with a clear message.
            throw new IllegalArgumentException("denominator must not be zero");
        }
        // Use direct division; no rounding is applied in this educational example.
        return numerator / denominator;
    }
}

In the BankAccount code below, what information do the inline comments provide in this program?

/**
 * Demonstrates a bank account with a simple transfer operation.
 */
public class BankAccount {
    private double balance;

    /**
     * Creates an account with a starting balance.
     *
     * @param startingBalance initial funds
     */
    public BankAccount(double startingBalance) {
        this.balance = startingBalance;
    }

    /**
     * Transfers money from this account to another account.
     *
     * @param other the destination account
     * @param amount the amount to transfer
     * @return true if the transfer succeeds
     */
    public boolean transferTo(BankAccount other, double amount) {
        if (other == null || amount <= 0) {
            // Invalid destination or amount: do not change either account.
            return false;
        }

        // Withdraw first; only deposit if withdrawal succeeds to avoid partial transfers.
        if (!withdraw(amount)) {
            return false;
        }
        other.deposit(amount);
        return true;
    }

    /**
     * Deposits money into the account.
     *
     * @param amount the amount to add
     */
    public void deposit(double amount) {
        if (amount <= 0) {
            return;
        }
        balance += amount;
    }

    /**
     * Withdraws money from the account.
     *
     * @param amount the amount to remove
     * @return true if successful
     */
    public boolean withdraw(double amount) {
        if (amount <= 0 || balance < amount) {
            return false;
        }
        balance -= amount;
        return true;
    }
}

/**

• Finds the maximum value in an array of integers.
• Precondition: nums.length > 0
• @param nums the array of integers to search
• @return the largest integer value in nums / public int findMax(int[] nums) { / implementation not shown */ }

Consider the provided findMax method. Which of the following is a postcondition of the method?

A programmer wants to add documentation to a Java method that can be processed by the Javadoc tool to generate API documentation. Which comment syntax must be used?

public void processItem(Item anItem) { anItem.updatePrice(); // ... more code }

Consider the processItem method, which takes an Item object as a parameter. Which of the following is the most critical implicit precondition for this method to avoid a NullPointerException?

/**

• Returns a new array containing the first n elements of the source array.
• Precondition: 0 <= n <= source.length
• @param source the original array
• @param n the number of elements to copy
• @return a new array with the first n elements / public int[] getPrefix(int[] source, int n) { / implementation not shown */ }

Consider the call getPrefix(myArray, 5), where myArray is an integer array of length 10. Which statement about this method call is true?

public int getSum(int[] data) { int total = 0; for(int x : data) { total += x; } return total; }

A programmer adds documentation to the getSum method. Which of the following is NOT a valid postcondition for this method, assuming its preconditions are met?

/**

• ... (description of method)
• @param index the position to access
• @return the element at the given index */

What information does the @param tag provide in a Javadoc comment?

/**

• Checks if two Rectangle objects have the same area.
• @param other the other Rectangle object to compare against
• @return true if the areas are the same, false otherwise / public boolean hasSameArea(Rectangle other) { / ... */ }

Which of the following is a necessary, implicit precondition for the hasSameArea method to avoid a NullPointerException?

/**

• Calculates the factorial of a non-negative integer n (n!).
• @param n the integer
• @return the factorial of n */ public int factorial(int n) { // implementation computes n * (n-1) * ... * 1 }

Which of the following is the most important precondition to add to the documentation for the factorial method to ensure it works as intended and avoids unintended behavior like infinite loops or incorrect results?