Lab Coding Exercise: Refactoring Code into Multiple Classes

This exercise is intended to help you to learn to critically read code, understand its purpose, and identify ways to make it more readable and changeable by improving its design using shorter methods and multiple classes. Along the way, start to build a sense of a reader's expectations about code and what makes one piece of code better than another given a specific set of design goals.

Submitting your Work

At the end of lab, use Gitlab's Merge Request from your forked repository's master branch back to the original organization repository's master branch to submit your group's answers to the discussion questions and your refactored code. Make sure the Title of your Merge Request is of the form "lab_hangman - everyone's NetIDs".

You only need to create one Merge Request, no matter how many commits you make, and you do not worry about potential conflicts since your request will not be approved (it is just an easy way for us to see what changes you made).

Lab Workflow

Here is a review of the steps you will use to work with GIT during lab (as distinct from assigned team projects):

1. On Gitlab, one person should fork the original project lab_hangman into their own repository to allow pushing your group's changes
   • On the resulting project web page, go to Project Information → Members (in the upper left corner) to add your partner so both people in the group can access the same repository
   • Search for your partner's name and give them a Maintainer role in the project and choose Add to Project
2. In Terminal, both students should use git clone to copy the one forked repository to their individual machines so they can work on their own separate copies
3. In IntelliJ, both students should Open the cloned folder to create a new project on their personal machine
4. In IntelliJ, add the names and NetIDs of everyone in your group at the top of the DISCUSSION.md file included in the repository
5. As a group, discuss how to change features in the current code and what design issues that reveals using the questions below as a guide
• Report your ideas, reasoning, and the main conclusions in the file DISCUSSION.md using Gitlab's Markdown format
6. In IntelliJ, refactor the code to improve its design (i.e., edit the code) using Pair Programming
7. In Terminal, use GIT to
• git add changed files
• git commit -m to describe your changes
• git push changes back to Gitlab
• git pull changes from Gitlab back to the local machine (if you are not sharing a single project using IntelliJ's Code With Me feature)
• Repeat as many times as needed, letting each person try the changes/GIT steps in related chunks
8. As a group, discuss the refactored design using the questions below as a guide.
   • Report your ideas, reasoning, and the main conclusions in the file DISCUSSION.md using Gitlab's Markdown format

Pair Programming

Labs in this course expect you to work either in pairs or with your project team.

Professionally, this practice is called Pair Programming: working closely with another programmer, sharing a "single computer" that we will simulate using a shared repository or IntelliJ's Code With Me feature. To ensure both people do some coding, you will switch which person actually writes the code every 10-15 minutes (in industry this switch happens only 1-3 times per day). The person who is not actively coding can be advising, suggesting better names, looking up documentation, or searching the Internet for solutions to small problems you are likely to face, but not multi-tasking (i.e., doing their own work or socializing).

Specification

The game of Hangman is a popular assignment given in CompSci 101 currently, and CompSci 201 previously. It is typically given in multiple parts based on what concept students are learning in the course, but the instructions tend to be the same: copy your previous version and update it to implement new kinds of players (either a guesser or secret word keeper). To simulate this in lab, there are two similar versions of the game that include four different kinds of players:

• an interactive guesser versus a secret word keeper that chooses a random secret word
• a guesser that chooses letters automatically based on their commonality versus an secret word keeper that changes the secret word after each guess to maximize the remaining possible words

The goal of this exercise is to use the commonalities and differences between the two game classes in the package game to identify what code is specific to guessers and secret word keepers (or generally, players) and extract that code into separate classes with methods that can be called from the game code instead of being included as part of the game class. In the end, instead of two classes with heavily duplicated code with no clear intentionality, you should have the following classes that represent distinct concepts with no duplicated code:

• HangmanGame
• Guesser
• SecretKeeper

Removing the duplication and decomposing one conceptual class into three will also improve the overall design by separating the game rules from the player logic so that they can be changed more easily and independently.

Note you only need to consider the code in the game package, not the util package.

Discussion

Examine the code from the perspective of how readable it is (i.e., is it easy to find or understand important parts of the code, does it do what you expect, does it require more or fewer comments). While studying this code, also note any good things about the code, that you might keep in the final version as well as smells in the code. If you have any questions about how it works, note those as well and talk to one of the Teaching Team to get your question resolved.

To begin discussing the code's design, spend some time evaluating the code using the following questions as a guide:

• What pieces of code help versus obscure your understanding?
• What comments could be removed and replaced with better variable names or by calling shorter methods?
• What Code Smells can you find?

To help identify candidate code within each game that could be turned into methods to represent a player's behavior, describe how would you make a new game using the current design with two new kinds of players:

• a clever guesser that automatically chooses letters based minimizing the remaining words versus an interactive secret word keeper that lets the user choose the secret word interactively

For this discussion, do not worry about the exact Java code needed to implement these players, just identifying what lines in one of the game classes needs to be changed to implement two new players described above. To guide your discussion, consider the following questions:

• What parts of the code do the game classes have in common and what parts are different (note, use can use Window → Editor Tabs → Split Right to view the two classes side by side)?
• The method play() is composed of several steps, which ones are essential to the game's rules and which to the two kinds of players' actions?
• The method handleGuess() is composed of several steps, which ones are essential to the game and which to the players?
• Which class (HangmanGame, Guesser, or SecretKeeper) should be responsible for these instance variables (and why): mySecretWord, myNumGuessesLeft, myDisplayWord, and myLettersLeftToGuess?

Refactoring

Refactoring is the practice of updating a program to improve its design and maintainability without changing its current functionality. An example of refactoring is creating a single method or class that replaces two or more sections of similar code because it reduces the amount of duplicate code within the program or makes the code easier to debug and test.

Your group may create any new methods or classes you want to help improve the program. Justify each change you make by explaining specifically how it improves the code in comments within the code. Justifications should refer specifically to principles discussed in class or the reading rather than using terms like "clearly/obviously", "good/sucks", or "like/hate".

Periodically create commits that represent a related set of changes (i.e., not just at the end of the lab or only each time you switch roles). After you think you have completed a reasonable goal, make a GIT commit with an appropriate comment (there should be at least four commits in your project history). After every two commits, push your changes up to Gitlab so your online repository reflects the work you have done in lab today and switch which person in the Programming Pair is typing.

Examine the given program and refactor it based on your group's discussion using the following steps (you should focus primarily on moving existing code rather than creating any new code):

1. Choose one game to refactor, rename it to HangmanGame, and extract the code you identified in your discussion that represent potential player code into methods for your new classes
2. Create a Guesser class that implements interactive guessing and update the HangmanGame class to use it in place of its own code and update the Main class to create the classes appropriately
3. Create an SecretKeeper class that implements choosing a random secret word and update the HangmanGame class to use it in place of its own code and update the Main class to create the classes appropriately
4. Update your Guesser class to implement choosing letters automatically by commenting out the interactive code — so no changes should need to be made to the HangmanGame or Main classes (we will see a better way to handle this next week)
5. Update your SecretKeeper class to implement changing the secret word after each guess by commenting out the interactive code — so no changes should need to be made to the HangmanGame or Main classes (again, we will see a better way to handle this next week)

After you have done as much as you think is reasonable, describe as concretely as you can how to implement these changes using this new version of the code:

• How would you change each of the new player classes to implement two new players described above (clever guesser and interactive secret keeper)?
  This should not require any changes to the primary game class.
  
• How would you create games featuring matchups between different types of players, rather than commenting and uncommenting code?
  This should require only adding if statements and parameters to the constructor sent from the main() method, not copying any existing classes.

Finally, consider the following questions:

• In what ways is the refactored code simpler and more intentional?
• In what ways is the refactored code more complex?
• What trade-offs did you make when refactoring the original code?
• Which code do you prefer and why?