The Challenge

The FinTech industry is really hot right now. Mark Erbergzuck realizes that he spends a lot of money on different purchases and would benefit from automatically summarizing his expenses. He receives monthly statements from his bank, but he finds them a bit overwhelming. He has tasked you with developing a piece of software that will automate the processing of his bank statements so he can get better insights into his finances. Challenge accepted!

The Goal

In this chapter, you will learn the foundations about good software development before learning more advanced techniques in the next few chapters.

You will start off by implementing the problem statement in one single class. You will then explore why this approach poses several challenges in terms of coping for changing requirements and maintenance of the project.

But do not worry! You will learn software design principles and techniques to adopt to ensure that the code you write meets these criteria. You will first learn about the Single Responsibility Principle (SRP), which helps develop software that is more maintainable, easier to comprehend, and reduces the scope for introducing new bugs. Along the way, you will pick up new concepts such as cohesion and coupling, which are useful characteristics to guide you about the quality of the code and software that you develop.

Bank Statements Analyzer Requirements

You had a delicious hipster latte (no added sugar) with Mark Erbergzuck to gather requirements. Because Mark is pretty tech-savvy, he tells you that the bank statements analyzer just needs to read a text file containing a list of bank transactions. He downloads the file from his online banking portal. This text is structured using a comma-separated values (CSV) format. Here is a sample of bank transactions:

30-01-2017,-100,Deliveroo
30-01-2017,-50,Tesco
01-02-2017,6000,Salary
02-02-2017,2000,Royalties
02-02-2017,-4000,Rent
03-02-2017,3000,Tesco
05-02-2017,-30,Cinema

He would like to get an answer for the following queries:

• What is the total profit and loss from a list of bank statements? Is it positive or negative?

• How many bank transactions are there in a particular month?

• What are his top-10 expenses?

• Which category does he spend most of his money on?

KISS Principle

Let’s start simple. How about the first query: “What is the total profit and loss from a list of bank statements?” You need to process a CSV file and calculate the sum of all the amounts. Since there is nothing else required, you may decide that there is no need to create a very complex application.

You can “Keep It Short and Simple” (KISS) and have the application code in one single class as shown in Example 2-1. Note that you do not have to worry about possible exceptions yet (e.g., what if the file does not exist or what if parsing a loaded file fails?). That is a topic that you will learn about in Chapter 3.

public class BankTransactionAnalyzerSimple {
    private static final String RESOURCES = "src/main/resources/";

    public static void main(final String... args) throws IOException {

        final Path path = Paths.get(RESOURCES + args[0]);
        final List<String> lines = Files.readAllLines(path);
        double total = 0d;
        for(final String line: lines) {
            final String[] columns = line.split(",");
            final double amount = Double.parseDouble(columns[1]);
            total += amount;
        }

        System.out.println("The total for all transactions is " + total);
    }
}

What is happening here? You are loading the CSV file passed as a command-line argument to the application. The Path class represents a path in the filesystem. You then use Files.readAllLines() to return a list of lines. Once you have all the lines from the file, you can parse them one at a time by:

• Splitting the columns by commas

• Extracting the amount

• Parsing the amount to a double

Once you have the amount for a given statement as a double you can then add it to the current total. At the end of the processing, you will have the total amount.

The code in Example 2-1 will work fine, but it misses a few corner cases that are always good to think about when writing production-ready code:

• What if the file is empty?

• What if parsing the amount fails because the data was corrupted?

• What if a statement line has missing data?

We will come back to the topic of dealing with exceptions in Chapter 3, but it is a good habit to keep these types of questions in mind.

How about solving the second query: “How many bank transactions are there in a particular month?” What can you do? Copy and paste is a simple technique, right? You could just copy and paste the same code and replace the logic so it selects the given month, as shown in Example 2-2.

final Path path = Paths.get(RESOURCES + args[0]);
final List<String> lines = Files.readAllLines(path);
double total = 0d;
final DateTimeFormatter DATE_PATTERN = DateTimeFormatter.ofPattern("dd-MM-yyyy");
for(final String line: lines) {
    final String[] columns = line.split(",");
    final LocalDate date = LocalDate.parse(columns[0], DATE_PATTERN);
    if(date.getMonth() == Month.JANUARY) {
        final double amount = Double.parseDouble(columns[1]);
        total += amount;
    }
}

System.out.println("The total for all transactions in January is " + total);

Code Maintainability and Anti-Patterns

Do you think the copy-and-paste approach demonstrated in Example 2-2 is a good idea? Time to take a step back and reflect on what is happening. When you write code, you should strive for providing good code maintainability. What does this mean? It is best described by a wish list of properties about the code you write:

• It should be simple to locate code responsible for a particular feature.

• It should be simple to understand what the code does.

• It should be simple to add or remove a new feature.

• It should provide good encapsulation. In other words, implementation details should be hidden from a user of your code so it is easier to understand and make changes.

A good way to think about the impact of the code you write is to consider what happens if a work colleague of yours has to look at your code in six months and you have moved to a different company.

Ultimately your goal is to manage the complexity of the application you are building. However, if you keep on copy pasting the same code as new requirements come in, you will end up with the following issues, which are called anti-patterns because they are common ineffective solutions:

• Hard to understand code because you have one giant “God Class”

• Code that is brittle and easily broken by changes because of code duplication

Let’s explain these two anti-patterns in more detail.

Single Responsibility Principle

The Single Responsibility Principle (SRP) is a general software development guideline to follow that contributes to writing code that is easier to manage and maintain.

You can think about SRP in two complementary ways:

• A class has responsibility over a single functionality

• There is only one single reason for a class to change¹

The SRP is usually applied to classes and methods. SRP is concerned with one particular behavior, concept, or category. It leads to code that is more robust because there is one specific reason why it should change rather than multiple concerns. The reason why multiple concerns is problematic is, as you saw earlier, it complicates code maintainability by potentially introducing bugs in several places. It can also make the code harder to understand and change.

So how do you apply SRP in the code shown in Example 2-2? It is clear that the main class has multiple responsibilities that can be broken down individually:

1. Reading input

2. Parsing the input in a given format

3. Processing the result

4. Reporting a summary of the result

We will focus on the parsing part in this chapter. You will learn how to extend the Bank Statements Analyzer in the next chapter so that it is completely modularized.

The first natural step is to extract the CSV parsing logic into a separate class so you can reuse it for different processing queries. Let’s call it BankStatementCSVParser so it is immediately clear what it does (Example 2-3).

public class BankStatementCSVParser {

    private static final DateTimeFormatter DATE_PATTERN
        = DateTimeFormatter.ofPattern("dd-MM-yyyy");

    private BankTransaction parseFromCSV(final String line) {
        final String[] columns = line.split(",");

        final LocalDate date = LocalDate.parse(columns[0], DATE_PATTERN);
        final double amount = Double.parseDouble(columns[1]);
        final String description = columns[2];

        return new BankTransaction(date, amount, description);
    }

    public List<BankTransaction> parseLinesFromCSV(final List<String> lines) {
        final List<BankTransaction> bankTransactions = new ArrayList<>();
        for(final String line: lines) {
            bankTransactions.add(parseFromCSV(line));
        }
        return bankTransactions;
    }
}

You can see that the class BankStatementCSVParser declares two methods, parseFromCSV() and parseLinesFromCSV(), that generate BankTransaction objects, which is a domain class that models a bank statement (see Example 2-4 for its declaration).

The BankTransaction class is useful so that different parts of our application share the same common understanding of what a bank statement is. You will notice that the class provides implementation for the methods equals and hashcode. The purpose of these methods and how to implement them correctly is covered in Chapter 6.

public class BankTransaction {
    private final LocalDate date;
    private final double amount;
    private final String description;


    public BankTransaction(final LocalDate date, final double amount, final String description) {
        this.date = date;
        this.amount = amount;
        this.description = description;
    }

    public LocalDate getDate() {
        return date;
    }

    public double getAmount() {
        return amount;
    }

    public String getDescription() {
        return description;
    }

    @Override
    public String toString() {
        return "BankTransaction{" +
                "date=" + date +
                ", amount=" + amount +
                ", description='" + description + ''' +
                '}';
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        BankTransaction that = (BankTransaction) o;
        return Double.compare(that.amount, amount) == 0 &&
                date.equals(that.date) &&
                description.equals(that.description);
    }

    @Override
    public int hashCode() {
        return Objects.hash(date, amount, description);
    }
}

Now you can refactor the application so that it uses your BankStatementCSVParser, in particular its parseLinesFromCSV() method, as shown in Example 2-5.

final BankStatementCSVParser bankStatementParser = new BankTransactionCSVParser();

final String fileName = args[0];
final Path path = Paths.get(RESOURCES + fileName);
final List<String> lines = Files.readAllLines(path);

final List<BankTransaction> bankTransactions
    = bankStatementParser.parseLinesFromCSV(lines);

System.out.println("The total for all transactions is " + calculateTotalAmount(bankTransactions));
System.out.println("Transactions in January " + selectInMonth(BankTransactions, Month.JANUARY));

The different queries you have to implement no longer need to know about internal parsing details, as you can now use BankTransaction objects directly to extract the information required. The code in Example 2-6 shows how to declare the methods calculateTotalAmount() and selectInMonth(), which are responsible for processing the list of transactions and returning an appropriate result. In Chapter 3 you will get an overview of lambda expressions and the Streams API, which will help tidy the code further.

public static double calculateTotalAmount(final List<BankTransaction> bankTransactions) {
    double total = 0d;
    for(final BankTransaction bankTransaction: bankTransactions) {
        total += bankTransaction.getAmount();
    }
    return total;
}

public static List<BankTransaction> selectInMonth(final List<BankTransaction> bankTransactions, final Month month) {

    final List<BankTransaction> bankTransactionsInMonth = new ArrayList<>();
    for(final BankTransaction bankTransaction: bankTransactions) {
        if(bankTransaction.getDate().getMonth() == month) {
            bankTransactionsInMonth.add(bankTransaction);
        }
    }
    return bankTransactionsInMonth;
}

The key benefit with this refactoring is that your main application is no longer responsible for the implementation of the parsing logic. It is now delegating that responsibility to a separate class and methods that can be maintained and updated independently. As new requirements come in for different queries, you can reuse the functionality encapsulated by the BankStatementCSVParser class.

In addition, if you need to change the way the parsing algorithm works (e.g., a more efficient implementation that caches results), you now have just a single place that needs to change. Moreover, you introduced a class called BankTransaction that other parts of your code can rely on without depending on a specific data format pattern.

It is a good habit to follow the principle of least surprise when you implement methods. It will help ensure that it is obvious what is happening when looking at the code. This means:

• Use self-documenting method names so it is immediately obvious what they do (e.g., calculateTotalAmount())

• Do not change the state of parameters as other parts of code may depend on it

The principle of least surprise can be a subjective concept, though. When in doubt, speak to your colleagues and team members to ensure everyone is aligned.

Cohesion

So far you have learned about three principles: KISS, DRY, and SRP. But you have not learned about characteristics to reason about the quality of your code. In software engineering you will often hear about cohesion as an important characteristic of different parts of the code you write. It sounds fancy, but it is a really useful concept to give you an indication about the maintainability of your code.

Cohesion is concerned with how related things are. To be more precise, cohesion measures how strongly related responsibilities of a class or method are. In other words, how much do things belong together? It is a way to help you reason about the complexity of your software. What you want to achieve is high cohesion, which means that the code is easier for others to locate, understand, and use. In the code that you refactored earlier, the class BankTransactionCSVParser is highly cohesive. In fact, it groups together two methods that are related to parsing CSV data.

Generally, the concept of cohesion is applied to classes (class-level cohesion), but it can also be applied to methods (method-level cohesion).

If you take the entry point to your program, the class BankStatementAnalyzer, you will notice that its responsibility is to wire up the different parts of your application such as the parser and the calculations and report back on the screen. However, the logic responsible for doing calculations is currently declared as static methods within the BankStatementAnalyzer. This is an example of poor cohesion because the concerns of calculations declared in this class are not directly related to parsing or reporting.

Instead, you can extract the calculation operations into a separate class called BankStatementProcessor. You can also see that the list of transactions method argument is shared for all these operations, so you can include it as a field to the class. As a result, your method signatures become simpler to reason about and the class BankStatementProcessor is more cohesive. The code in Example 2-7 shows the end result. The additional advantage is that the methods of BankStatementProcessor can be reused by other parts of your application without depending on the whole BankStatement​Analyzer.

public class BankStatementProcessor {

    private final List<BankTransaction> bankTransactions;

    public BankStatementProcessor(final List<BankTransaction> bankTransactions) {
        this.bankTransactions = bankTransactions;
    }

    public double calculateTotalAmount() {
        double total = 0;
        for(final BankTransaction bankTransaction: bankTransactions) {
            total += bankTransaction.getAmount();
        }
        return total;
    }

    public double calculateTotalInMonth(final Month month) {
        double total = 0;
        for(final BankTransaction bankTransaction: bankTransactions) {
            if(bankTransaction.getDate().getMonth() == month) {
                total += bankTransaction.getAmount();
            }
        }
        return total;
    }

    public double calculateTotalForCategory(final String category) {
        double total = 0;
        for(final BankTransaction bankTransaction: bankTransactions) {
            if(bankTransaction.getDescription().equals(category)) {
                total += bankTransaction.getAmount();
            }
        }
        return total;
    }
}

You can now make use the methods of this class with the BankStatementAnalyzer as shown in Example 2-8.

public class BankStatementAnalyzer {
    private static final String RESOURCES = "src/main/resources/";
    private static final BankStatementCSVParser bankStatementParser = new BankStatementCSVParser();

    public static void main(final String... args) throws IOException {

        final String fileName = args[0];
        final Path path = Paths.get(RESOURCES + fileName);
        final List<String> lines = Files.readAllLines(path);

        final List<BankTransaction> bankTransactions = bankStatementParser.parseLinesFrom(lines);
        final BankStatementProcessor bankStatementProcessor = new BankStatementProcessor(bankTransactions);

        collectSummary(bankStatementProcessor);
    }

    private static void collectSummary(final BankStatementProcessor bankStatementProcessor) {
        System.out.println("The total for all transactions is "
                + bankStatementProcessor.calculateTotalAmount());

        System.out.println("The total for transactions in January is "
                + bankStatementProcessor.calculateTotalInMonth(Month.JANUARY));

        System.out.println("The total for transactions in February is "
                + bankStatementProcessor.calculateTotalInMonth(Month.FEBRUARY));

        System.out.println("The total salary received is "
                + bankStatementProcessor.calculateTotalForCategory("Salary"));
    }
}

In the next subsections, you will focus on learning guidelines to help you write code that is easier to reason and maintain.

public class BankTransactionDAO {

    public BankTransaction create(final LocalDate date, final double amount, final String description) {
        // ...
        throw new UnsupportedOperationException();
    }

    public BankTransaction read(final long id) {
        // ...
        throw new UnsupportedOperationException();
    }

    public BankTransaction update(final long id) {
        // ...
        throw new UnsupportedOperationException();
    }

    public void delete(final BankTransaction BankTransaction) {
        // ...
        throw new UnsupportedOperationException();
    }
}

public class BankTransactionParser {

    public BankTransaction parseFromCSV(final String line) {
        // ...
        throw new UnsupportedOperationException();
    }

    public BankTransaction parseFromJSON(final String line) {
        // ...
        throw new UnsupportedOperationException();
    }

    public BankTransaction parseFromXML(final String line) {
        // ...
        throw new UnsupportedOperationException();
    }
}

Testing

You have written some software and it looks like things are working if you execute your application a couple of times. However, how confident are you that your code will always work? What guarantee can you give your client that you have met the requirements? In this section, you will learn about testing and how to write your first automated test using the most popular and widely adopted Java testing framework: JUnit.

Using JUnit

Hopefully you are now convinced of the value of writing automated tests. In this section, you will learn how to create your first automated test using a popular Java framework called JUnit. Nothing comes for free. You will see that writing a test takes time. In addition, you will have to think about the longer-term maintenance of the test you write since it is regular code, after all. However, the benefits listed in the previous section far outweigh the downsides of having to write tests. Specifically, you will write unit tests, which verify a small isolated unit of behavior for correctness, such as a method or a small class. Throughout the book you will learn about guidelines for writing good tests. Here you will first get an initial overview for writing a simple test for the BankTransactionCSVParser.

Defining a test method

The first question is where do you write your test? The standard convention from the Maven and Gradle build tools is to include your code in src/main/java and the test classes inside src/test/java. You will also need to add a dependency to the JUnit library to your project. You will learn more about how to structure a project using Maven and Gradle in Chapter 3.

Example 2-14 shows a simple test for BankTransactionCSVParser.

Note

Our BankStatementCSVParserTest test class has the Test suffix. It is not strictly necessary, but often used as a useful aide memoire.

Example 2-14. A failing unit test for the CSV parser

import org.junit.Assert;
import org.junit.Test;
public class BankStatementCSVParserTest {

    private final BankStatementParser statementParser = new BankStatementCSVParser();

    @Test
    public void shouldParseOneCorrectLine() throws Exception {
        Assert.fail("Not yet implemented");
    }

}

There are a lot of new parts here. Let’s break it down:

• The unit test class is an ordinary class called BankStatementCSVParserTest. It is a common convention to use the Test suffix at the end of test class names.

• The class declares one method: shouldParseOneCorrectLine(). It is recommended to always come up with a descriptive name so it is immediately obvious what the unit test does without looking at the implementation of the test method.

• This method is annotated with the JUnit annotation @Test. This means that the method represents a unit test that should be executed. You can declare private helper methods with a test class, but they won’t be executed by the test runner.

• The implementation of this method calls Assert.fail("Not yet implemented"), which will cause the unit test to fail with the diagnostic message "Not yet implemented". You will learn shortly how to actually implement a unit test using a set of assertion operations available in JUnit.

You can execute your test directly from your favorite build tool (e.g., Maven or Gradle) or by using your IDE. For example, after running the test in the IntelliJ IDE, you get the output in Figure 2-2. You can see the test is failing with the diagnostic “Not yet implemented”. Let’s now see how to actually implement a useful test to increase the confidence that the BankStatementCSVParser works correctly.

Figure 2-2. Screenshot from the IntelliJ IDE of running a failing unit test

Assert statements

You have just learned about Assert.fail(). This is a static method provided by JUnit called an assert statement. JUnit provides many assert statements to test for certain conditions. They let you provide an expected result and compare it with the result of some operation.

One of these static method is called Assert.assertEquals(). You can use it as shown in Example 2-15 to test that the implementation of parseFrom() works correctly for a particular input.

Example 2-15. Using assertion statements

@Test
public void shouldParseOneCorrectLine() throws Exception {
    final String line = "30-01-2017,-50,Tesco";

    final BankTransaction result = statementParser.parseFrom(line);

    final BankTransaction expected
        = new BankTransaction(LocalDate.of(2017, Month.JANUARY, 30), -50, "Tesco");
    final double tolerance = 0.0d;

    Assert.assertEquals(expected.getDate(), result.getDate());
    Assert.assertEquals(expected.getAmount(), result.getAmount(), tolerance);
    Assert.assertEquals(expected.getDescription(), result.getDescription());
}

So what is going on here? There are three parts:

1. You set up the context for your test. In this case a line to parse.

2. You carry out an action. In this case, you parse the input line.

3. You specify assertions of the expected output. Here, you check that the date, amount, and description were parsed correctly.

This three-stage pattern for setting up a unit test is often referred to as the Given-When-Then formula. It is a good idea to follow the pattern and split up the different parts because it helps to clearly understand what the test is actually doing.

When you run the test again, with a bit luck you will see a nice green bar indicating that the test succeeded, as shown in Figure 2-3.

Figure 2-3. Running a passing unit test

There are other assertion statements available, which are summarized in Table 2-2.

Table 2-2. Assertion statements

Assertion statement	Purpose
Assert.fail(message)	Let the method fail. This is useful as a placeholder before you implement the test code.
Assert.assertEquals​(expected, actual)	Test that two values are the same.
Assert.assertEquals​(expected, actual, delta)	Assert that two floats or doubles are equal to within a delta.
Assert.assertNotNull(object)	Assert that an object is not null.

Takeaways

• God Classes and code duplication lead to code that is hard to reason about and maintain.

• The Single Responsibility Principle helps you write code that is easier to manage and maintain.

• Cohesion is concerned with how how strongly related the responsibilities of a class or method are.

• Coupling is concerned with how dependent a class is on other parts of your code.

• High cohesion and low coupling are characteristics of maintainable code.

• A suite of automated tests increases confidence that your software is correct, makes it more robust for changes, and helps program comprehension.

• JUnit is a Java testing framework that lets you specify unit tests that verify the behavior of your methods and classes.

• Given-When-Then is a pattern for setting up a test into three parts to help understand the tests you implement.

Iterating on You

If you want to extend and solidify the knowledge from this section, you could try one of these activities:

• Write a couple more unit test cases to test the implementation of the CSV parser.

• Support different aggregate operations, such as finding the maximum or minimum transactions in specific date ranges.

• Return a histogram of the expenses by grouping them based on months and descriptions.

Completing the Challenge

Mark Erbergzuck is very happy with your first iteration of your Bank Statements Analyzer. He takes your idea and renames it THE Bank Statements Analyzer. He is so happy with your application that he is asking you for a few enhancements. It turns out he would like to extend the reading, parsing, processing, and summarizing functionalities. For example, he is a fan of JSON. In addition, he found your tests a bit limited and found a couple of bugs.

This is something that you will address in the next chapter, where you will learn about exception handling, the Open/Closed Principle, and how to build your Java project using a build tool.