Unit 1.8: Documentation with Comments and Preconditions

Scope: CS Awesome 2, Section 1.8

Learning Goals

By the end of this lesson, you should be able to:

1. Choose among line, block, and Javadoc comments.
2. Write useful documentation rather than narrating obvious code.
3. State a method's preconditions and postconditions.
4. Explain software validity and use cases.
5. Compare sequential and iterative development at a high level.

Why Comments Matter

Comments communicate with people who read and maintain code. The compiler ignores them, so comments do not execute.

Good comments explain purpose, assumptions, constraints, or non-obvious decisions.

// Use cents to avoid floating-point round-off in account balances.
int balanceInCents = 1250;

This comment explains why the representation was chosen.

// Add one to count.
count++;

This comment merely repeats obvious code and adds little value.

Three Comment Forms

Line Comment

// Everything after these characters is a comment.

Block Comment

/*
 * A block comment can span multiple lines.
 * It ends at the closing marker.
 */

Javadoc Comment

/**
 * Returns the distance traveled at a constant speed.
 * @param speed distance traveled per hour
 * @param hours elapsed time in hours
 * @return total distance traveled
 */

Javadoc comments begin with /** and can be processed into API documentation. Tags such as @param and @return describe a public contract.

Preconditions

A precondition is something that must be true immediately before a section of code runs for it to behave as expected.

/**
 * @param total total quantity to distribute
 * @param groups number of groups
 * Precondition: groups > 0
 */
public static int eachGroup(int total, int groups)
{
    return total / groups;
}

The caller is responsible for satisfying a documented precondition unless the method states that it validates the input.

Postconditions

A postcondition describes what must be true after code executes successfully. It can describe a return value or an object's changed state.

/**
 * Precondition: count >= 0
 * Postcondition: returns a value exactly one greater than count
 */
public static int nextCount(int count)
{
    return count + 1;
}

Preconditions define what the code expects; postconditions define what the code promises.

Software Validity and Use Cases

Software validity asks whether software does what its requirements say it should do. Testing should include normal inputs, boundary values, and attempts to violate assumptions.

A use case describes a way an actor interacts with a system. For a library checkout system:

Actor: member
Use case: borrow book
Preconditions: member account is active; book is available
Postconditions: book is assigned to member; availability is updated

The postcondition of one use case often becomes a precondition for a later use case.

Development Models

A sequential waterfall model completes one major phase before moving to the next. Agile development uses short, iterative cycles to build, test, deliver, and collect feedback repeatedly.

Validity still matters in either model. The difference is when feedback and adaptation occur.

Preconditions and postconditions are AP CSA concepts. Use-case diagrams and development-process details provide professional context beyond the core exam requirement.

Practice Missions

Mission 1: Improve the Comment

Replace each weak comment with one that provides useful information, or explain why no comment is needed.

// Set total to price times quantity.
double total = price * quantity;

// Add 1.
attempts++;

Mission 2: Contract for a Temperature Converter

Write a Javadoc contract for a method with this header:

public static double toKelvin(double celsius)

Include @param, @return, a physically meaningful precondition, and a precise postcondition. Do not implement the method.

Mission 3: Break the Assumption

The method pagesPerDay(int pages, int days) uses integer division. State appropriate preconditions, then give one normal test, one boundary test, and one invalid test.

Mission 4: Use-Case Chain

For a parcel locker system, document the preconditions and postconditions of these use cases:

1. courier deposits parcel;
2. recipient opens locker;
3. system marks locker available.

Show how one postcondition becomes the next precondition.

Key Summary

Concept	Core idea
//	Comment through the end of one line.
/* */	Block comment.
/** */	Javadoc comment for API documentation.
Precondition	Must be true before execution.
Postcondition	Guaranteed after successful execution.
Validity	Software satisfies its requirements.
Use case	An actor's interaction with a system.

Source scope: CS Awesome 2, Unit 1.8