Lesson 24.1 – Make the SuperAdventure source code easier to understand and modify

Lesson objectives

At the end of this lesson, you will know…

• How to use Visual Studio, to help you clean up source code
• How to make your source code easier to read, which makes it easier to find bugs and make changes

There are thousands of different ways to write any program. Many of them will work as well as any other.

However, you need to remember that some other programmer may need to make changes to it in the future. And, that future programmer may be you (in six months, when you’ve forgotten exactly why you wrote your code the way you did).

In this lesson, I’ll show you some common techniques to make your code easier to understand – and how to use Visual Studio to help you do this.

None of the changes involve any new skill. They are only creating new properties, methods, and renaming a few things. However, I believe you’ll see a version of SuperAdventure that is much easier to work with.

NOTE: This refactoring changed 13 files. If you don’t want to make all these changes to your SuperAdventure program, I suggest that you still read through the lesson and compare your code with the refactored code here. This will give you an idea of how your future programs should look – with smaller functions, and improved names.

Video of me doing some of the refactoring steps

I’m using Visual Studio Community 2015 in this video. Older versions may not have the same refactoring tools, or they may work differently.

Use source control, when refactoring code

When you refactor your program, or make any large group of changes, it’s very helpful to use source control.

Before you make changes, check your code into your source code repository. After you make your changes, test your program. If it still works, check in the new version of your source code. If the changes don’t work, and you can’t fix them, you can “revert/rollback” your code to what it was before you started the changes.

If you are not familiar with source control, you can watch this video on Installing TortoiseSVN (Subversion) and VisualSVN for Visual Studio 2015 on Windows 10. These are the same source control tools I use at home, and at the office.

Step 1: At the top of many of our classes, we have several “using” statements. Some of them are added when Visual Studio creates the class file. However, we usually don’t need all of them. We will clean up our classes by removing those excess lines.

Start Visual Studio, open Player.cs, and look at the “using” statements. You should see that these two lines are light grey:

using System.Text;
using System.Threading.Tasks;

They are light grey because the Player class does not use any classes from those namespaces. So, we can remove them.

If you look at most of the other classes, you’ll notice different “using” statements that are light grey, and can also be removed.

You could go through each file, and manually remove all these lines, but there is an easier way.

In Visual Studio’s menu, click on Edit -> IntelliSense -> Organize Usings -> Remove and Sort Usings. This will remove all the un-needed “using” lines, and sort the remaining ones in alphabetical order. You don’t need to do the sort, but I like to keep them organized.

After doing this, I click the “Save All” button in Visual Studio’s menu, and run the game, to make sure it still works.

It all worked, so I committed these changes to the source code repository. Remember to check in your changes after each successful refactoring change.

Step 2: Make your comparisons sound more like a natural language.

Sometimes, “if” conditions can be very complex. They might check several different values, and use complex combinations of “if”, “and”, and “not”. This can also happen when a comparison contains negatives – some value “does not” equals another value.

To make these easier to understand, you can change the variable, property, function, or series of comparisons to sound like how you would naturally speak.

For these situations, “wrap” the unnatural-sounding comparison behind a new function, or property, that has a clearer name.

For example, in the Player MoveTo() function, we have this line, to see if a location has a quest:

// Does the location have a quest
if(newLocation.QuestAvailableHere != null)

The “if” statement doesn’t sound very natural when you read it aloud – at least, not to me.

So, I created a new property in the Location class that wraps that comparison. It does the exact same logic, but with a more natural name. Here’s the code for that function:

public bool HasAQuest { get { return QuestAvailableHere != null; } }

Now, we can change the code in MoveTo() to this:

if(newLocation.HasAQuest)

This line sounds much more natural, and easier to understand.

It’s so clear, I removed the comment from the line above it. This is what “self-documented code” means. The source code is so easy to read, and understand, that you need very few comments.

I made several more similar changes to SuperAdventure, creating new properties and functions, with names that sound more natural.

Step 3: “Inline” variables that are only used once, especially if they are used almost immediately after they are created.

Sometimes, we create variables that are only used once. They may serve the same purpose as the “wrapper” property we created in the previous step – to put a complex evaluation in an easy-to-understand location.

But, if we have well-named variables, properties, and functions, and we only use that variable in a few places, we can eliminate that variable (and that line of code) by placing its value “inline”.

On line 318 of the Player class, we have:

bool playerAlreadyHasQuest = HasThisQuest(newLocation.QuestAvailableHere);

We only use that variable in one place, three lines later, on line 321.

if(playerAlreadyHasQuest)

To eliminate the temporary variable, click on it and press Ctrl + . (the period/full stop key). This pulls up Visual Studio’s refactoring tool. Choose “Inline temporary variable”.

Visual Studio will show you where it will make the change, and you can click the “Apply” button to complete the change.

Another line of code is eliminated.

I did this for several more variables that were only used once (or a few times), and were used almost immediately after they were created.

NOTE: Sometimes, you may want to keep a single-use variable in your code, and not “inline” it. If you debug your program, you can set a breakpoint to see what happens when the variable is populated. That may be a little easier to follow than setting the breakpoint on the “if” statement. It’s one less thing happening on the line of code where you set the breakpoint.

Step 4: Give variables, properties, and functions more descriptive names.

If you have unclear names for properties, functions, or variables, and they don’t need to be “wrapped”, you can easily rename them in one place – and Visual Studio can update them every place they are used.

Left-click on a variable, property, or function name. It should have a light grey background.

Now, press the “F2” key. The background should turn green, and a box will pop up in the upper-right corner of the editing screen. Start typing, and Visual Studio will replace the name of your variable/property/function – every place it is used in your solution.

You can check the options in the pop-up box if you also want Visual Studio to change the name if it exists in comments or strings in your solution. If you check the “Preview Changes” box, Visual Studio will show you every place it will make the change, when you click the “Apply” button. In the preview, you can uncheck places where you don’t want the change made, before Visual Studio does the replacement.

Step 5: Break large functions into smaller functions that only do one thing.

The MoveTo function is large, does a lot of things, and difficult to understand.

When you see a function like this, look for the parts that have one purpose. Move those lines of code to their own function, and have the large function call that new, smaller function.

The smaller function will be easier to understand. It only has one purpose and has fewer lines and variables. Plus, the larger function will now have one line, where it used to have 15-30 lines. That will make the larger function easier to read.

When you see lines of code that you would like to move to a separate function, highlight them, click Ctrl + . (to bring up the refactoring menu), and click on “Extract Method”. Give the new method a name, and Visual Studio will create the function. It will also replace the lines you highlighted with a call to the new function.

Here is what the Player MoveTo function looks like, before and after all the refactoring changes.

BEFORE

public void MoveTo(Location newLocation)
{
    //Does the location have any required items
    if(!HasRequiredItemToEnterThisLocation(newLocation))
    {
        RaiseMessage("You must have a " + newLocation.ItemRequiredToEnter.Name + " to enter this location.");
        return;
    }
    // Update the player's current location
    CurrentLocation = newLocation;
    // Completely heal the player
    CurrentHitPoints = MaximumHitPoints;
    // Does the location have a quest?
    if(newLocation.QuestAvailableHere != null)
    {
        // See if the player already has the quest, and if they've completed it
        bool playerAlreadyHasQuest = HasThisQuest(newLocation.QuestAvailableHere);
        bool playerAlreadyCompletedQuest = CompletedThisQuest(newLocation.QuestAvailableHere);
        // See if the player already has the quest
        if(playerAlreadyHasQuest)
        {
            // If the player has not completed the quest yet
            if(!playerAlreadyCompletedQuest)
            {
                // See if the player has all the items needed to complete the quest
                bool playerHasAllItemsToCompleteQuest = HasAllQuestCompletionItems(newLocation.QuestAvailableHere);
                // The player has all items required to complete the quest
                if(playerHasAllItemsToCompleteQuest)
                {
                    // Display message
                    RaiseMessage("");
                    RaiseMessage("You complete the '" + newLocation.QuestAvailableHere.Name + "' quest.");
                    // Remove quest items from inventory
                    RemoveQuestCompletionItems(newLocation.QuestAvailableHere);
                    // Give quest rewards
                    RaiseMessage("You receive: ");
                    RaiseMessage(newLocation.QuestAvailableHere.RewardExperiencePoints + " experience points");
                    RaiseMessage(newLocation.QuestAvailableHere.RewardGold + " gold");
                    RaiseMessage(newLocation.QuestAvailableHere.RewardItem.Name, true);
                    AddExperiencePoints(newLocation.QuestAvailableHere.RewardExperiencePoints);
                    Gold += newLocation.QuestAvailableHere.RewardGold;
                    // Add the reward item to the player's inventory
                    AddItemToInventory(newLocation.QuestAvailableHere.RewardItem);
                    // Mark the quest as completed
                    MarkQuestCompleted(newLocation.QuestAvailableHere);
                }
            }
        }
        else
        {
            // The player does not already have the quest
            // Display the messages
            RaiseMessage("You receive the " + newLocation.QuestAvailableHere.Name + " quest.");
            RaiseMessage(newLocation.QuestAvailableHere.Description);
            RaiseMessage("To complete it, return with:");
            foreach(QuestCompletionItem qci in newLocation.QuestAvailableHere.QuestCompletionItems)
            {
                if(qci.Quantity == 1)
                {
                    RaiseMessage(qci.Quantity + " " + qci.Details.Name);
                }
                else
                {
                    RaiseMessage(qci.Quantity + " " + qci.Details.NamePlural);
                }
            }
            RaiseMessage("");
            // Add the quest to the player's quest list
            Quests.Add(new PlayerQuest(newLocation.QuestAvailableHere));
        }
    }
    // Does the location have a monster?
    if(newLocation.MonsterLivingHere != null)
    {
        RaiseMessage("You see a " + newLocation.MonsterLivingHere.Name);
        // Make a new monster, using the values from the standard monster in the World.Monster list
        Monster standardMonster = World.MonsterByID(newLocation.MonsterLivingHere.ID);
        _currentMonster = new Monster(standardMonster.ID, standardMonster.Name, standardMonster.MaximumDamage,
            standardMonster.RewardExperiencePoints, standardMonster.RewardGold, standardMonster.CurrentHitPoints, standardMonster.MaximumHitPoints);
        foreach(LootItem lootItem in standardMonster.LootTable)
        {
            _currentMonster.LootTable.Add(lootItem);
        }
    }
    else
    {
        _currentMonster = null;
    }
}

AFTER

public void MoveTo(Location location)
{
    if(PlayerDoesNotHaveTheRequiredItemToEnter(location))
    {
        RaiseMessage("You must have a " + location.ItemRequiredToEnter.Name + " to enter this location.");
        return;
    }
    // The player can enter this location
    CurrentLocation = location;
    CompletelyHeal();
    if(location.HasAQuest)
    {
        if(PlayerDoesNotHaveThisQuest(location.QuestAvailableHere))
        {
            GiveQuestToPlayer(location.QuestAvailableHere);
        }
        else
        {
            if(PlayerHasNotCompleted(location.QuestAvailableHere) &&
               PlayerHasAllQuestCompletionItemsFor(location.QuestAvailableHere))
            {
                GivePlayerQuestRewards(location.QuestAvailableHere);
            }
        }
    }
    SetTheCurrentMonsterForTheCurrentLocation(location);
}

The MoveTo function has gone from over 100 lines, to only 31 lines. The other lines are all in small functions, usually around 20 lines each.

If you want to change the SuperAdventure game – maybe add new features – it will be much easier to do with this smaller MoveTo function.

Step 6: Repeat, until all the code is easy to understand.

When you program, it’s usually a good idea to refactor often. After each change, look for anything you can clean up.

Think of it like changing the oil in a car. If you always drive (add code), and never change your oil (refactor), eventually, your engine (and program) will break down. Then, it will take much longer time to repair.

I’ve worked on programs that have been in development for years, with dozens of programmers making changes and additions. Many times, management will say that we don’t have time to clean up the code – we need to add in new features, “Now!”.

But, eventually, the code gets so bad that every change causes something new to break. When you keep your code clean, you reduce these problems.

Summary

When you create large programs, or programs that are modified long after they are written, it helps to have the code easy to read and understand.

I’ve worked on several projects that are millions of lines long, have been in development for years, and have had more than a dozen programmers work on them. When the code is not easy to understand, changes take longer, and are more likely to break something.

If you frequently do these refactoring techniques, your code will be much easier to work with.

Source code for this lesson

Source code on GitHub

Source code on Dropbox

Next lesson: Lesson 25.1 – Select a random monster at a location

Previous lesson: Lesson 23.1 – Creating a console front-end for the game

All lessons: Learn C# by Building a Simple RPG Index