CompSci 308
Spring 2025		 Advanced Software Design and Implementation

OOGASalad : Design Specifications

You will be accountable for ensuring that your code's design meets these specifications that you have practiced in previous projects. The table below follows the format in the Design Requirements Glossary.

Design is more important than functionality for your final grade and you should not expect to meet all the design requirements by simply getting it “working” right before the deadline.

ID Name Adherence Description
DESIGN-01 Multiple Classes Complete Code should be divided into several classes that each have a useful purpose (i.e., non-get/set methods). Avoid these code smells: large class and data clumps.
DESIGN-02 Meaningful Names Complete Give variables, methods, classes, and packages non-abbreviated, intention-revealing names to support Clean Code and reduce the need for comments.
DESIGN-03 Named Constants Complete Named constants, including numbers, strings, and Enums, for values used multiple times or in program logic. This includes being declared as final variables with an intention revealing name.
DESIGN-04 Don’t Repeat Yourself (DRY) Complete The same lines of code should not appear in multiple different places in the same project (i.e., they should not be duplicated). Instead, the code should be refactored so that the duplicated logic is written only once and called from many places.
DESIGN-05 Interact Through Methods Complete Classes should avoid inappropriate intimacy by collaborating via method calls. A class should not directly access the instance variables of another class. Do not use public instance variables or global variables.
DESIGN-06 Code Formatting Complete Code should follow course formatting conventions, including things that cannot be automatically checked, especially the Java naming conventions.
DESIGN-07 Tightly Scoped Methods Complete Each method should be small and single-purpose. Long methods should be decomposed into smaller pieces of functionality. Long methods are a code smell.
DESIGN-08 Comments Complete Follow Javadoc conventions for commenting on public classes, interfaces, methods, and packages. In-line comments should be used judiciously; self-explanatory code is preferred. See Internal Documentation.
DESIGN-09 Model View Separation Complete GUIs should be separate from the model; this requires clear articulation about what information (including errors) needs to be communicated between each part.
NOTE: You may optionally include a Controller from Model-View-Controller if your team has complex logic for handling user inputs that results in code duplication or tight coupling between View components.
  • The View should be a collection of classes in package called oogasalad.view and its sub-packages. View classes in these packages use OpenJFX to display to the user and interact with the Model.
  • The Model should be a collection of classes in a package called oogasalad.model and its sub-packages. View classes in the these packages should not import any classes from javafx.*; being agnostic to how the information is presented to user.
DESIGN-10 Encapsulation Complete Key implementation details must be hidden such that they can be changed without impacting any other classes.
DESIGN-11 Make and Use Abstractions Complete Create abstractions that capture commonality (superclasses or interfaces) and encourage variability (subclasses or implementors). Build your classes to depend on the abstractions (superclasses and interfaces) rather than implementations (concrete subclasses).
EXAMPLES:
  • Use the most abstract collection possible (i.e., List instead of ArrayList and Map instead of HashMap)
  • Do not downcast to specific subclasses or use instanceof checks (except in equals() methods)
DESIGN-12 Automated Testing Complete Your program must be tested using JUnit (with assertions both for typical situations and possible thrown Exceptions) to verify it works as intended. Tests should be written in separate classes and methods that follow these naming standards. These tests should be a mix of:
  • Model Tests: tests that test one small unit of functionality
  • End-to-End Tests: tests that simulate the user interacting with user interface (using TestFX)

Your testing goals are to:

  • write JUnit Tests for each concrete class with at least two well-named tests for each non-trivial public method (more than two for complex methods)
  • write at 10 negative scenario JUnit Tests where the expected behavior is to throw an Exception
  • achieve at least 80% line test coverage overall
NOTE: Each person must push at least four commits each week to the main branch that creates or updates tests.
DESIGN-13 Programs Should Not Crash Complete Build robustness into your program so that it does not crash or hang. Handle errors and provide a reasonable response to exceptional cases so that the user can continue to run the program.
DESIGN-14 Handle Errors Using Exception Flows Complete Communicate errors in a thoughtful, intentional, manner rather than returning null or other error prone values.
Consider using custom Exceptions or Java's Optional.
DESIGN-15 Externalize Configuration Complete Move hardcoded values into configuration files, stored in src/main/resources, rather than compiled into your program, specifically:
  • "magic" values stored as static final constants
  • any text displayed in the user interface, by using resource property files (the String.format() method allows you to make any complex string a single value)
  • any styles (colors, font, borders, etc.) used to customize the user interface, by using CSS files

NOTE: Each program should support at least three Theme options (such as Dark or Light modes, Duke or UNC colors, larger fonts for presentation mode, etc.) and at least three languages (Pig Latin is a popular option or you can use Google Translate if no one on your team can do it).

DESIGN-16 No Dead Code Complete Your project should not include unused variables, methods, or classes. Do not comment out blocks of code to save them for later; instead, use your GIT history to find old code.
DESIGN-17 Explicit Immutability Complete For classes and values that should not change after they are instantiated, explicitly restrict them from changing using language features.
Consider using Enumerated types or Records.
DESIGN-18 APIs Complete Provide well-defined Application Programming Interfaces (API)s for logical parts of your project. The View should only interact with APIs.
Each public API class and method should have complete Javadoc comments, especially interfaces and abstract classes to show their intended use.
Each API package must include a file called package-info.java that includes comments to describe the API's Design Goals and Contracts.
NOTE: Use packages named api to represent an External API that contain only abstractions (Java interfaces or abstract classes), purely immutable classes, or Exceptions. The internal code, consisting primarily of concrete subclasses, should be in sub-packages that are not imported or known about directly by outside packages.
DESIGN-19 Reflection for Instantiation from Strings Complete Use reflection whenever you need to create objects or call methods from Strings rather than hardcoding conditionals or a mapping between the String literal and your object.
DESIGN-20 Apply Design Patterns Complete Define and describe your system design using Design Patterns.
Your classes should follow the naming conventions of the design pattern you are applying (i.e., a factory class from the Factory pattern should be named with the suffix Factory).
Document your Design Patterns where appropriate, such as Javadoc comments and the project DESIGN document.
DESIGN-21 Logging Complete Use Log4j2, instead of println() statements to output messages.
A message must be generated any time an Exception is thrown that is saved to one or more files within the folder log.
Messages labeled as DEBUG or INFO can go to the console (standard out) or a file.

GIT Specifications

To show you are using GIT to effectively deliver functionality incrementally, your project repository must show many, purposeful commits and all team members need to integrate each other's work regularly rather than having marathon merge or redesign sessions because everyone's code has drifted from a common design.

ID Name Adherence Description
GIT-01 Commit Message Format Complete Commit messages must follow this format and must always reference either a feature or design requirement.
GIT-02 Feature Commits Complete Make at least one commit for each feature you implement
GIT-03 Refactor Commits Complete Make at least two commits for each design requirement that show the results of refactoring existing code to improve its design
GIT-04 Fix Commits Complete Make at least one commit for each bug you fix after you have committed an existing feature
GIT-05 Close Issues Complete Close or update Feature Issues as you make progress on them (sort of like a progress bar for programming).
You can do this either on your project's Gitlab Issue page or by using keywords within your commits.
GIT-06 Tag Significant Commits Complete Use Tags to identify important commits by memorable label instead of indistinguishable hash value.
  • git tag example: use after an important commit (like completion of several related features or after the final version)
  • git push --tags: use to push your tags to the course repository so others can see them
Copyright 2025 Last modified 17 Mar 2025 Feedback?