[…] on any non-trivial project (more than about 1 week of coding or more than one programmer), if you don’t have a spec, you will always spend more time and create lower quality code. ~ Joel Spolsky

A specification is an efficient way to communicate a design with others. As professional software is almost always developed by teams, a specification ensures that there is consensus on the design before progressing with its implementation.

Expected duration
4–6 hours
Deadline
2359 on Lesson 31
Points
50 points
Submission
Canvas

Learning Objectives

Prepare written software engineering artifacts

  • Write requirements for a software system
  • Write a use case to document requirements
  • Model an object-oriented system using a UML class diagram
  • Formulate test cases from requirements

Help Policy

Authorized Resources
Any, except others’ work related to this assignment
Notes
Never copy another person’s work and submit it as your own

Do not jointly work on this assignment, but you may ask classmates questions

You must document all help received from all sources, including the instructor and instructor-provided material (including the textbook)

Instructions

You are responsible for writing a specification to model and visualize a Rubik’s Cube. A Rubik’s Cube is a 3-dimensional puzzle invented in 1974 by Ernő Rubik. The cube comprises 26 miniature cubes (also known as “cubies” or “cubelets”) where the visible face(s) of each miniature cube is a different color and each face of the cube may be rotated independently of the others. When solved, each face of the cube must have only a single color. Various algorithms exist to solve a Rubik’s Cube, but the focus of this assignment is modeling and visualizing a Rubik’s Cube so that someone can “play” with an electronic version.

Rubik's cube

Your specification will be peer reviewed by others in the class (and you will be responsible for peer reviewing others’ specifications). In a subsequent assignment, you will implement a specification for modeling and visualizing a Rubik’s Cube.

When you write a specification, exhaustive detail is not necessary, but someone else must be able to implement it. If struggling to understand how much detail to include, the specification for Sudoku can be used as a reference. (Hint: More information is generally better, and although exhaustive detail is neither required nor appropriate, always trend toward including more information whenever in doubt.) A more entertaining resource is Joel Spolsky’s series “Painless Functional Specifications,” which addresses this topic humorously and pragmatically.

For consistency, you must use the provided template for the specification. The specification template is derived from those used by OpenStack.

Use the provided template for the specification.

When writing a specification, be careful to avoid conflating requirements and design. A requirement is an expression of desired behavior that does not reference the proposed system – i.e., a requirement dictates “what” whereas the design dictates “how” a requirement will be satisfied.

Submission

Submit a PDF of your specification using the Canvas. Be sure to include your documentation statement as part of the submission.

After submission, you must complete peer reviews of others’ specification. These peer reviews will be assigned automatically and should be completed by Lesson 32.

Grading

The following grading rubric will be used for this assignment:

Criteria Points
Problem description, including requirements and use case(s) 20
Design, including alternatives 20
Testing 5
Formatting and Grammar 5

Each criteria will be scored using the following scale:

Superb (100%)
No issues
Proficient (90%)
Trivial issues (e.g., opportunities for clarification), but no content changes necessary
Competent (75%)
Minor issue that requires revision
Marginal (50%)
Major issue or multiple minor issues that requires significant revision
Unsatisfactory (25%)
Multiple major issues that require complete revision

Resources

Painless Functional Specifications