Writing Big Programs

Throughout this course so far, we’ve written several programs. But we may start to notice that we are repeating lines of code over and over again.

As programs get bigger, it can also be difficult to manage all of the code and make sure we are not missing something. A small typing error in one part of the code can become very difficult to find when there is so much code to check.

For example, consider a program that needs to write the same output to multiple output files. Right now, if we wanted to write that program, it might contain code that performs these steps:

open file1
write to file1
write to file1
close file1

open file2
write to file2
write to file2
close file2

open file3
write to file3
write to file3
close file3

open file4
write to file4
write to file4
close file4

As we can see, much of the code in that program is repeated, with only small parts changed. Is there a different way we could write this program to make it simpler?

Methods

Video Materials

The answer lies in the use of methods in our code. A method is a piece of code that can be used by our program to perform an action. However, the biggest benefit of using a method comes from the fact that we can use methods multiple times, helping us avoid repeated code in our programs. We can also provide input to our methods and receive output from our methods, allowing a single method to perform work on a wide variety of data.

Let’s look at an updated version of our previous example - a program that writes the same output to multiple files:

public static void main(String[] args){
    outputToFile("file1.txt");
    outputToFile("file2.txt");
    outputToFile("file3.txt");
    outputToFile("file3.txt");
}

public static void outputToFile(String filename){
    BufferedWriter writer = new BufferedWriter(new FileWriter(filename));
    writer.write("This is the first line of " + filename);
    writer.newLine();
    writer.write("This is the end of the file");
    writer.newLine();
    writer.close();
}

In the Java code above, we have defined two methods, one called main just like we’ve seen many times before, and another method named outputToFile that we can use to write data to a file with the name stored in the filename parameter. The body of the functions are delimited with {}. Just like conditional statements and loops, all method definitions must have a body.

The first method, named main, is the actual code that runs when our program is executed.

The other method, outputToFile, actually performs the work of outputting to the file.

To use a method, we’ve included code that looks like outputToFile("file1.txt"); in our main method. That line is known as a method call or method invocation, which will then execute the code inside of the outputToFile method. So, we might say that we are using that line to “call outputToFile” or “call the outputToFile method”. Either way is correct!

Of course, we also need to be able to provide input to our method, as we do in this example. The next page will describe how that works in more detail.

Parameters & Arguments

When we are writing methods in our code, we may need to provide some input to our methods. This allows our method to perform the same action using different data each time, making them much more flexible. So, let’s look at how to do that in theory and discuss some of the terminology we’ll need to understand first.

Parameters

When we define a method, we can also list a number of parameters, or inputs, that the method can accept. Depending on the language we are using, we may need to provide either a name, or possibly a type and a name for each parameter. In addition, many languages allow us to accept variable length parameters, which we’ll cover in detail later in this module.

So, in our code, we can define a method that accepts parameters in this way:

public static void foo(String parameter1, String parameter2){
    System.out.println(parameter1);
    System.out.println(parameter2);
}

Typically, each parameter is listed in the method’s definition. So, this example defines a method named foo that accepts two parameters, parameter1 and parameter2. Together, they make up the method’s signature, which allows our programs to find them. Therefore, no two methods may share the same signature. Instead, they must either use a different name, or a different number of parameters. In statically typed languages such as Java, we can also vary the types of each parameter instead, not just the number of parameters.

Arguments

Of course, when we want to call a method in our code, we must provide values for each parameter. Those values are known as arguments to the method. In code, it might look something like this:

public static void main(String[] args){
    foo("abc", "xyz");
}

In that example, we see foo("abc", "xyz"), which is calling our method named foo. Inside, it provides two arguments, one for each parameter of the method. So, inside of our method, the variable parameter1 will be "abc", and parameter2 will be "xyz". Pretty straightforward, right?

Returning a Value

Finally, we may also want to get a result back from our methods, especially if it is performing a calculation or some other task for us. So, we can use a special keyword known as return to provide a value as output from our method. In general, if you call a method that returns a value, you want to catch that value in a variable.

Let’s look at an example:

public static void main(String[] args){
    output = max(5, 42, 3)
    System.out.println(output);
}

public static int max(int a, int b, int c){
    if (a >= b && a >= c){
        return a
    } else if (b >= a && b >= c){
        return b
    } else {
        return c
    }
}

In this example, we have defined a method named max which will return the largest value of its three parameters, a, b, and c. So, in our main method, we are calling output with arguments 5, 42, and 3, which will be stored as a, b, and c, respectively.

Then, in the max method, we use an If-Else statements to determine which one is larger than the other two, and then return that value. So, if we look closely at the code, we should be able to see that it will return 42 as the largest value.

As we can see, our code can contain multiple return statements. However, the method will stop executing as soon as it reaches the first return statement, and will therefore only return a single value. This is really handy if we know the answer we need to output; we can just use the return keyword to stop what we are doing and provide the output.

So, once our max method is complete, the value 42 will be returned. In our main method, that value will be stored in the output variable. So, values returned from a method can be used in an assignment statement, just like any other value. In fact, we can treat a method call just like a variable! As soon as our program reaches a method call, it will stop what it is doing, execute the method, and replace the method call with the returned value. It’s a really handy way to organize our code.

That covers the basics of how a method is created in our code. On the next few pages, we’ll discuss some related topics that will help us understand how these methods work and how we can structure our code to take advantage of methods.

Variable Scope

Another topic we must revisit is variable scope. Recall from an earlier chapter we learned how variables may only be referenced after they’ve been defined, and in many cases only within the method or block they are defined in. Now that we are dealing with multiple methods, we must once again discuss variable scope and how it applies to this situation.

Method Scope

In general, all of the scope rules we’ve learned still apply. For example, a variable declared in a method can only be accessed within that method. In that way, different methods may use the same variable names to refer to different variables. In addition, as we’ve seen in the earlier examples, a method may define parameters using the same variable names as the variables that are used as arguments to that method. It may seem confusing to some, but to others it makes perfect sense.

Class Scope

Most programming languages also allow us to create variables at the class level, inside a class but outside of any method. Those variables can then be referenced within any of the class’s method, allowing us to share data between methods without using parameters and return values.

Here’s a quick example in code:

public class MathOperations {

    double PI = 3.1415926535;

    public static void main(String[] args){
        double r = 3.0;
        double area = calculateArea(r);
        System.out.println(area);
    }

    public static double calculateArea(double r){
        return r * r * PI;
    }

} 

In this example, we have created a class variable named PI to store the value of $ \pi $ for our entire program. Then, we can use that variable just like any other inside of the calculateArea method.

Of course, we can assign and edit class variables just like any other variable:

public class Foo{
    static int people = 1;

    public static void main(String[] args){
        people = people + 1;
        foo();
        System.out.println(people);
    }

    public static void foo(){
        people = people * 3;
    }
}

In this example, the main method will print $ 6 $ as the value of people. Since that variable is declared in the class scope, it can be accessed and changed by any method.

Shadowing Variables– Using the Same Variable Names

Sometimes we may want to have a variable inside of our methods use the same name as a class variable, this is a type of shadowing. Shadowing occurs whenever an inner scope name hides (in its shadow) an outer scope variable of the same name. Here’s a modified version of the code above showing that situation:

public class Foo{
    static int people = 1;

    public static void main(String[] args){
        int people = 1;
        people = people + 1;
        foo();
        System.out.println(people);
    }

    public static void foo(){
        people = people * 3;
    }
}

In this example, the variable people is redeclared inside of the main function. So, it is an entirely different variable than the class variable named people. Because of this, whenever we use the variable people inside of main, we are referring to the method scope or local scope variable people. Therefore, the class-scope value is not updated by the main method, and main will simply print $ 2 $ instead of $ 6 $.

Shadowing is not necessarily bad, and may be unavoidable in large programs using multiple imported modules. It is something that a developer should always be aware of, since it can have unintended consequences.

DRY: Don't Repeat Yourself

One major mantra among programmers is Don’t Repeat Yourself (DRY), and it’s a very important concept to keep in mind when writing programs that can use methods. In essence, anytime we find ourselves writing the same or similar code multiple times in our program, we may want to ask ourselves if it would be better to make that piece of code a method. That way, we only have to write it once, and if there are any problems with that code, we only have to remember to change it in one place instead of everywhere we’ve used it.

DRY Example

To really understand how DRY can improve our code, let’s look at a quick example:

import java.lang.Math;

public class Dry{

    public static void main(String[] args){
        int a = 1;
        int b = 0;
        int c = -4;
        double rootOne = (-b - Math.sqrt(b * b - 4 * a * c)) / (2 * a);
        double rootTwo = (-b + Math.sqrt(b * b - 4 * a * c)) / (2 * a);
        System.out.println(rootOne);
        System.out.println(rootTwo);

        a = 2;
        b = 7;
        c = 3;
        rootOne = (-b - Math.sqrt(b * b - 4 * a * c)) / (2 * a);
        rootTwo = (-b + Math.sqrt(b * b - 4 * a * c)) / (2 * a);
        System.out.println(rootOne);
        System.out.println(rootTwo);
    }
}

Of course, this is a very simple example calculating the roots of a quadratic equation.

However, we see that this program repeats many lines of code to perform the same basic calculation with different values. We can easily move that calculation to a new method, and then use parameters to set the values. So, let’s apply the DRY principle to simplify this program:

import java.lang.Math;

public class Dry{

    public static void main(String[] args){
        quadratic(1, 0, -4);
        quadratic(2, 7, 3);
    }

    public static void quadratic(int a, int b, int c){
        rootOne = (-b - Math.sqrt(b * b - 4 * a * c)) / (2 * a);
        rootTwo = (-b + Math.sqrt(b * b - 4 * a * c)) / (2 * a);
        System.out.println(rootOne);
        System.out.println(rootTwo);
    }
}

There! We’ve moved all of the code for calculating the roots for the quadratic equation, printing each root at the end. Then, we can simplify the code in main by simply calling that method anytime we want to calculate the roots .

This could be further reduced by “pre calculating” the discriminant since it is used twice in the quadratic function.

import java.lang.Math;

public class Dry{

    public static void main(String[] args){
        quadratic(1, 0, -4);
        quadratic(2, 7, 3);
    }

    public static void quadratic(int a, int b, int c){
        d = discriminant(a, b, c);
        rootOne = (-b - Math.sqrt(d)) / (2 * a);
        rootTwo = (-b + Math.sqrt(d)) / (2 * a);
        System.out.println(rootOne);
        System.out.println(rootTwo);
    }

    public static int discriminant(int a, int b, int c){
        return b * b - 4 * a * c;
    }
}

We can also extend this code to make use of the fact that the value of the discriminant tells us how many different roots a quadratic equation will have. By moving code to functions, we can quickly find additional ways to expand upon and improve our programs.

Properly following the DRY principle when writing code will make our programs simpler, easier to maintain, and hopefully easier to debug. In effect, it is definitely a good idea to add a new method to our code anytime we find ourselves typing something twice, or copy and pasting code.

Writing Testable Code

Another big idea related to writing methods in our code relates to testing. Specifically, how can we write methods that are easily testable?

Unit Testing

We won’t go deep into the details in this course, but most programming languages support unit testing, which is the use of automated testing tools to make sure each piece of code works as intended. They are very important for two big reasons:

1. A properly written set of tests will help confirm that the code works as intended in the first place
2. Tests that previously passed but fail after an update to our code may highlight an unintended side effect of the changes we made

In fact, many of the automated grading tools in this course make extensive use of unit testing to confirm that our code is working properly, both within this tutorial textbook and in the standalone projects. Now that we are writing code that contains methods, unit tests will become an even bigger part of the grading process in this course.

Writing Testable methods

There are entire textbooks written about the theory of writing code that can be easily tested, and not everyone agrees exactly what the best model is. However, there are a few things that we can keep in mind as we write methods to make them easily testable:

1. Each method should only perform one action: a method should only do one thing. For example, if a program needs to read data from a file and then write that data to another file, those are two different actions and could be considered two separate methods.
2. Avoid non-deterministic effects: where possible, avoid a method that returns different values for the same inputs. This could include choosing a random value, or using the system time or other uncontrollable input in the method. These methods are difficult to test due to their random nature. If your method needs a random number, have that number passed in as a parameter.

In the examples later in this course, we’ll see explicitly how to follow some of these guidelines when writing our own code. For now, they are just handy things for us to keep in mind.

Testing Your Code

Developers are also Testers

Up to this point in the class we’ve had various automated grading tools available to test our code and make sure it works correctly. However, it is important to understand that these buttons are just running code written by other developers (in this case, the instructors of the course), and these tests can have the same limitations as any other program. For example, it is often impossible to guarantee that these tests will accurately test all possible inputs or reach 100% code coverage. Likewise, depending on how the solution is written, the edge cases and boundary conditions may be different than the ones that were originally used for testing.

At this point, we have learned enough programming syntax and terminology to start running our programs manually and developing our own tests. So, from this point forward, many of the projects will not give us access to the full automated grading process before we submit it. In effect, it is now our job to properly test our program using various inputs, both the ones provided and ones that we develop ourselves, in order to be sure that it is working properly.

After we submit the project, the full autograder will still be used to grade our work. The autograder will confirm that your project matches the specification within a reasonable limit. However, we won’t be able to go back in and make any changes after we submit the project. So, we’ll have to be extra careful and make sure our programs are fully tested before we submit them.

Write a test Method

One thing that we can do is add an explicit test method to any class in our program. Our test method may contain any code needed to test our program. We are always allowed to add additional methods to any class as needed - we won’t be penalized for that in grading.

For example, we could add a test method to the previous example to test some of the functions:

import java.lang.Math;

public class Dry{

    public static void main(String[] args){
        quadratic(1, 0, -4);
        quadratic(2, 7, 3);
    }

    public static void quadratic(int a, int b, int c){
        d = discriminant(a, b, c);
        rootOne = (-b - Math.sqrt(d)) / (2 * a);
        rootTwo = (-b + Math.sqrt(d)) / (2 * a);
        System.out.println(rootOne);
        System.out.println(rootTwo);
    }

    public static int discriminant(int a, int b, int c){
        return b * b - 4 * a * c;
    }

    public static void test(){
        int answer1 = discriminant(1, 3, 1);
        System.out.println("Answer 1 was " + answer1 + " and should be 5");
        int answer2 = discriminant(3, 3, 3);
        System.out.println("Answer 2 was " + answer1 + " and should be 27");
    }
}

In the method, we see that we are calling the discriminant method with a few different values. The expected answer values we see in the print statements can be manually calculated and verified using a calculator. It is important that we calculate these manually instead of relying on our program to calculate them - if we did, how would we ever know if it was actually incorrect?

Using a test Method

Once we’ve written a test method, we have to change our program so that it calls the method. The simplest way to do this is to just add that function call at the very top of the main() method:

    public static void main(String[] args){
        test();
        quadratic(1, 0, -4);
        quadratic(2, 7, 3);
    }

Since the test method may produce output or change the functionality of our program, it is always important to remember to REMOVE the test method from our main method before we submit the program.

Summary

As the programs we develop become larger and more complex, we’ll definitely rely on the ability to create methods to help make our code easier to read, debug, and maintain. methods allow us to write small, self-contained pieces of code that can be reused over and over again, or break large operations into smaller, simpler steps.

From this point forward, nearly any program we write will contain multiple methods. In fact, it is very rare to see any programs beyond just simple scripts that don’t contain at least a few methods.

In the next few modules, we’ll also see how to build classes that represent real-world objects, as well as how to add methods inside of those classes called methods to represent how those objects method in the real world.