Lab Coding Exercise: Refactoring Code

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.

Submission

While there will not be an official submission for this exercise, this code will be the basis for this week's programming exercise.

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 Settings -> Members 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 computer)
• 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

Specification

CompSci 101 currently, and CompSci 201 previously, give an assignment based on the game of Hangman. 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 interactive secret word keeper that lets the user choose the secret word

The goal of this exercise is to use the commonalities and differences between the different game classes in the package game to identify what code is specific to guessers and secret word keepers (or generally, players) and extract those differences into separate classes with methods that can be called from the game code instead of being part of the game class. In the end, instead of two classes with heavily duplicated code that represent one concept, 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 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, consider how would you make a new game using the current design:

• a clever guesser that automatically chooses letters based minimizing the remaining words versus a secret word keeper that changes the secret word after each guess to maximize the remaining possible words

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?
• The method playGuess() is composed of several steps, which ones make sense as part of the game's rules and which as part of the two kinds of 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 significantly. 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 (and comment why you choose to create them) any new methods or classes you want to help improve the program. Try to justify each change you make by explaining specifically how it improves 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 discuss when you think it is appropriate to create a commit that represents 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.

Examine the given program and refactor it based on your group's discussion using the following steps:

1. Choose one game to refactor, rename it to HangmanGame, and try to extract the methods you identified in your discussion that represent potential player code within that game
2. Create a Guesser class that implements interactive guessing and update the HangmanGame class to use it instead of its own methods 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 instead of its own methods and update the Main class to create the classes appropriately
4. Update your Guesser class to implement choosing letters automatically and update the Main class to create the classes appropriately (and comment out the interactive version)
5. Update your SecretKeeper class to implement changing the secret word after each guess and update the Main class to create the classes appropriately (and comment out the random version)

After you have done as much as you think is reasonable, answer the following questions in the DISCUSSION.md file:

• In what ways is the refactored code simpler?
• 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?

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 computer, shared repository or use IntelliJ's new 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).