UNIT 1.8

Documentation with Comments

AP Computer Science A

Using Objects and Methods

Learning Objective 1.8.A

Describe the functionality and use of code through comments.

What are Comments?

Comments are written explanations in code that:
  • Help programmers understand code and its functionality
  • Are ignored by the compiler
  • Are not executed when the program runs
  • Serve as documentation for both original and future programmers

Key Point: Comments are for humans to read, not for the computer to execute!

Three Types of Comments in Java

1. Single-Line Comments: //

Creates a comment on one line

// This is a single-line comment int age = 16; // Another comment explaining this variable

2. Multi-Line Comments: /* */

Creates a block of comments spanning multiple lines

/* This is a multi-line comment that can span several lines to explain complex code */

3. Javadoc Comments: /** */

Used to create API documentation

/** This is a Javadoc comment * Used for generating documentation * @param name the student's name * @return the formatted greeting */

Comment Examples in Practice

public class Student { private String name; // Student's name private int grade; // Current grade level /* Constructor to create a new Student object with the given name and grade */ public Student(String studentName, int currentGrade) { name = studentName; grade = currentGrade; } /** * Returns a formatted string with student information * @param includeGrade whether to include grade in output * @return formatted student information */ public String getInfo(boolean includeGrade) { // Implementation details here... return name + (includeGrade ? " - Grade " + grade : ""); } }

Preconditions

Precondition: A condition that must be true just prior to the execution of a method in order for it to behave as expected.

Important: There is no expectation that the method will check to ensure preconditions are satisfied.

Example:

/** * Calculates the square root of a number * Precondition: x >= 0 (x must be non-negative) * @param x the number to find square root of * @return the square root of x */ public double sqrt(double x) { // Method assumes x is non-negative return Math.sqrt(x); }

The method assumes the caller will pass a non-negative value.

Postconditions

Postcondition: A condition that must always be true after the execution of a method.

Postconditions describe the outcome of execution in terms of:

  • What is being returned
  • The current value of object attributes

Example:

/** * Adds a student to the class roster * Precondition: student is not null * Postcondition: student is added to roster, roster size increases by 1 * @param student the student to add */ public void addStudent(Student student) { roster.add(student); // Postcondition: roster.size() is now 1 greater than before }

Comment Best Practices

DO:

  • Explain why code exists
  • Document complex algorithms
  • Specify preconditions and postconditions
  • Keep comments up-to-date
  • Use Javadoc for public methods

DON'T:

  • State the obvious
  • Write comments that repeat code
  • Leave outdated comments
  • Use comments to fix bad code
  • Write novels in comments

Remember: Good code should be self-documenting, with comments adding valuable context!

Good vs. Bad Comments

Bad Comments

// Increment i i++; // Set name to student name this.name = studentName; // Check if x equals 5 if (x == 5) {

These comments just repeat what the code already says!

Good Comments

// Process next item in queue i++; // Store name for grade report generation this.name = studentName; // Check if maximum attempts reached if (attempts == MAX_ATTEMPTS) {

These comments explain the purpose and context!

Unit 1.8 Summary

Key Takeaways:

  • Comments document code for human readers, not computers
  • Three types: // (single-line), /* */ (multi-line), /** */ (Javadoc)
  • Preconditions: What must be true before method execution
  • Postconditions: What must be true after method execution

Essential Knowledge 1.8.A: Use comments to describe functionality, document preconditions and postconditions, and help other programmers understand your code.

Good documentation makes good programmers!

1 / ?