Login

Title

Writing Javadoc Comments for a Class

Course

CS1

Abstract

This assignment combines implementing a class definition (constructors, getters, setters for a Rectangle) with using Javadoc comments to document the class. This assignment includes background information on the Javadoc tool, including information about technical requirements (such as the @param tag) and style guidelines for javadocs (guidelines nicely summarized on Oracle's website). The rubric includes separate items for both the technical part of the assignment (writing the class) and the Javadoc part of the assignment. This could be easily modified to incorporate Javadocs with some other programming assignment.

This assignment assumes that students are able to implement a basic class definition in Java, with constructors, getters, and setters.

Author

Norm Krumpe

Genre

Javadocs

Assignment Duration

One Week

Communication Skill

Writing

Technical Skill

Class creation, documentation

Workplace Scenario

Organizations write code that must be sufficiently documented in order for other team members (current and future) to use that code. Often, such documentation must be written using a given set of requirements (as defined by an employer or by some broader community).

In this assignment, you will be writing code, along with the documentation for that code. There are two kinds of standards for that documentation:

  1. Technical standards: the documentation you write needs to be parsable by a piece of software that turns your comments into a web page. The Javadoc standards are documented on Oracle's web page, "How to Write Doc Comments for the Javadoc Tool"
  2. Human standards: the documentation you write needs to be written in a grammatic style that is consistent with how others write similar documentation. The community style for these standards is documented on the same Oracle web page, in the "Style Guide" section.

Team Size

N/A

Collection

Citation

Norm Krumpe, “Writing Javadoc Comments for a Class,” Incorporating Communication Outcomes into the Computer Science Curriculum, accessed September 21, 2017, http://cs-comm.lib.muohio.edu/items/show/17.

License

Creative Commons License

Comments

Allowed tags: <p>, <a>, <em>, <strong>, <ul>, <ol>, <li>