1. PROJECT: BrainTrain

This project portfolio page showcases my coding, documentation and other contributions to the BrainTrain project.

2. Overview

As a student of the CS2103T: Software Engineering module, I was tasked with working with 4 other students as a team to build a product from an existing address book application over 7 weeks. We were given a choice to morph the existing address book to any application we want and we chose to develop BrainTrain to further challenge ourselves.

BrainTrain is a spaced repetition flashcard application which makes memorizing easy and efficient. User interaction happens through Command Line Interface (CLI) and it has a minimal Graphical User Interface (GUI) created with JavaFX. It is written in Java, and has about 16 kLoC.

My role was to design and build the app’s quiz mode. The following sections detail what I have contributed to the project, and showcases my ability to write user and developer documentation.

3. Summary of contributions

  • Major enhancement: Implementation of quiz mode

    • What it does: Quiz mode manages user interaction during a quiz. It comprises of 6 commands which are only available in this mode. It also reads in answer inputs.

      • [ANSWER]…​ - Answers the current question. All inputs without the prefix \ are treated as answers.

      • \difficult - Labels current question in quiz as difficult or not.

      • \help - Lists all commands in quiz and inputs the program will accept.

      • \hint - Reveals additional information to help user to solve the question.

      • \quit - Quits a quiz and save attempted progress.

      • \status - Lists current status and lesson progress of user.

    • Justification: Users need to be able to launch a lesson in quiz mode, where they will be tested on the lesson’s flashcards, in order to use BrainTrain for memorization.

    • Highlights: Pull request #32, #42, #96, #129, #175, #186

  • Minor enhancement: Implementation of quiz mode display to user.

    • What it does: In order to cater for two different mode, there will be 2 different display. Display will switch smoothly between management mode and quiz mode.

    • Justification: This is to ensure that there is no unnecessary display to distract the user during a quiz mode. The user just need to focus solely on going through the flashcard without having to care about the list of lesson available.

    • Highlights: Pull request #108

  • Code contributed: [RepoSense]

  • Other contributions:

    • Project management:

      • Managed 3 out of 6 releases v1.1, v1.3.1 and v1.4 on GitHub

    • Team contribution:

      • Integrated AddressBook features with BrainTrain (#33)

      • Improved test coverage from 88% to 95% by writing all the BrainTrain system tests (#175)

      • Implemented ChangeThemeCommand to change between light and dark theme which persists beyond app restart. (#175)

    • Documentation:

      • Updated Architecture, Logic, UI and QuizModel component diagram to match the current implementation. (#186)

    • Community:

      • Reviewed pull requests with constructive feedback (examples: #30, #87, #97, #121)

      • Contributed to forum discussions (examples: #49, #51)

      • Reported bugs and suggestion for other team in the class (examples: #106, #118, #140)

      • Assisted Evan in adding a legend footer to his management mode (#106)

4. Contributions to the User Guide

Given below is an extract of my contributions to the user guide.

Start of extract of quiz mode

4.1. Quiz mode

When you start a quiz, you will enter quiz mode. In this mode, you will only be allowed to enter the following set of quiz commands. Management commands are disabled in this mode.

4.1.1. Answering a card : [ANSWER]

An input without the \ prefix will be treated as an answer to the current card.
Format: [ANSWER]…​

Usage rules:

  • You can answer with one or more words (e.g. "Tokyo" or "Aland Islands").

What a card contains:

  • For each card, total attempts and answer streak are tracked.

  • Total attempts refers to the number of times you have attempted this card, regardless of whether you were answered it correctly.

  • The answer streak is the number of times you have answered the card correctly consecutively.

The streak will be reduced to 0 after you answer a card wrongly twice in a row. Hence, if you accidentally enter the wrong answer once, your streak for the question will not be affected, unless you answer wrongly again.
You can press ENTER twice without entering any other input to reveal the answer.

Going through the different scenarios in a quiz:

Step 1:
The question is "Japan" and is asking for the capital of "Japan":
Enters Tokyo as answer
The picture shown below shows the expected result if the question has been answered correctly, which the total correct question counter increased by 1.

answer tokyo correctly
Figure 1. Expected result of answering the question correctly.


Step 2:
The question is "Tokyo" and is asking for the country of "Tokyo":
Enters Japaan as wrong answer
The picture shown below shows the expected result if the question has been answered wrongly once, which the total attempts counter increased by 1.

answer japan wrongly once
Figure 2. Expected result of answering the question wrongly once.


Step 3:
Same question as above, "Tokyo" and is asking for the country of "Tokyo":
Enters Jappan as another wrong answer
The picture shown below shows the expected result if the question has been answered wrongly twice, which shows the correct answer and the total attempts counter increased by 1.

answer japan wrongly twice
Figure 3. Expected result of answering the question wrongly twice.


Step 4:
Same question as above, "Tokyo" and is asking for the country of "Tokyo":
Enters Japan as correct answer
The picture shown below shows the expected result if the question has been answered correctly after answer has been revealed, which shows how well each question is performed in this quiz.

answer end
Figure 4. Expected result of quiz after questions have been completed.


4.1.2. Viewing the current card’s hint(s): \hint

Reveals the hint(s) for the current card (if any).
Format: \hint

Example:

  • Enters \hint
    Reveals the hint of the current card

hint
Figure 5. Expected result revealing the hint of the card.

4.1.3. Quitting the quiz session: \quit

Quits the current quiz session and switches back to management mode.
Format: \quit

Example:

  • The question is "Japan" and is asking for the capital of "Japan":
    Enters Tokyo as answer
    Enters \quit to quit the quiz.
    Saves the progress of 1 attempted question "Japan".

quit
Figure 6. Expected result of quitting a quiz after answering a question correctly.


End of extract of quiz mode

5. Contributions to the Developer Guide

Given below is an extract of my contribution to the developer guide.

Start of extract of quiz mode

5.1. Quiz feature

Quiz feature allows users to enter quiz related commands and answer.

5.1.1. Current implementation

The quiz feature processes the following inputs:

  • [ANSWER]…​ - An input without a prefix \ is treated as an answer.

  • \difficult - Labels current question as difficult or not.

  • \help - Lists all quiz commands and inputs which will be accepted.

  • \hint - Reveals additional information to help the user to answer the question.

  • \quit - Quits quiz mode and saves attempt progress.

  • \status - Lists current quiz progress.

5.1.2. Quiz class

Quiz.java holds all the in-memory quiz data. It takes in a list of cards from Session. Then, it generates an expanded list of cards based on the mode indicated by the user. The generated list of cards in both review and learn mode includes cards which questions and answers are flipped. This to ensure that users are memorizing both question and answer values. According to the mode which the user has chosen, the cards will be displayed differently as seen below.

In the four different modes:

  • Preview: both the question and answer are shown to the user.

quiz preview
Figure 7. Question displayed in preview mode.

  • Review: only the question is shown as the user needs to answer the question.

quiz review
Figure 8. Question displayed in review mode.

  • Learn: is a combination of preview and review, the user sees both the question and answer as in preview mode, before attempting the question with the answer hidden as in review mode.

quiz learn
Figure 9. Question displayed in learn mode.

  • Difficult: similar to preview mode but only contains questions which have been labelled as difficult.

5.1.3. Quiz answer command: [ANSWER]

AnwerComponetSequenceDiagram
Figure 10. High-level sequence diagram for the ANSWER command, an example of completing a quiz.

The [ANSWER] feature is facilitated by QuizAnswerCommand. The command takes in user input as answer, which will be processed later when the command is executed.

The following sequence diagram shows the interaction between the various classes when the user answered the question correctly:

QuizAnswerCommandSequenceDiagram
Figure 11. Sequence diagram for answer feature

In the execute method of the QuizAnswerCommand, the following steps can be performed:

  1. Quiz result
    This step checks if the user is shown the result, this is performed because the quiz can only end after the result has been shown. Once the quiz ends, BrainTrain will save the progress of the quiz to the file specified by the user.

  2. Handling of answer
    This step checks if the answer should be handled, if user is in PREVIEW mode it will not be handled. Otherwise, the total attempts and streak of the question will be updated depending on whether the question has been answered correctly.

  3. Handling of next question
    This step verifies that the question has been answered correctly, and checks if there are still questions left for the current quiz. Depending on the check, it will then displays the next question or the quiz result.

The following code shows how the steps could be performed:

public CommandResult execute(Model model, CommandHistory history) throws CommandException {
    requireNonNull(model);
    this.quizModel = requireQuizModel(model);
    this.card = quizModel.getCurrentQuizCard();
    this.isCurrentCardWrong = false;

    StringBuilder sb = new StringBuilder();

    if (quizModel.isResultDisplay()) {
        endQuiz();
        return new CommandResult("", true, false, false);
    }

    if (card.isWrongTwice() || card.getQuizMode() != QuizMode.PREVIEW) {
        sb.append(handleCurrentCardAnswer());
    }

    if (!isCurrentCardWrong) {
        String result = handleIfCardLeft();
        sb.append(result);
    }

    return new CommandResult(sb.toString(), true, false, false);
}

5.1.4. Design considerations

Aspect: quiz and management commands execution

  • Alternative 1 (current choice): Run quiz in a different mode

    • Pro: Least restricted choice of answer and great user experience.

    • Con: Tedious to implement.

  • Alternative 2: Run quiz together with the rest of the commands

    • Pro: Easy to implement.

    • Con: Restricted answer and compromised user experience. Answer cannot start with words already reserved for management commands. (e.g. start)

Alternative 1 is chosen because it allows the user to have a more flexible choice of word. For certain questions, it is possible for the answer to be "start". Hence by choosing alternative 1, the choice of answer will not be restricted. Also, by running the quiz in a different mode, it allows the user to have intuitive interaction in quiz mode. End of extract of quiz mode