By: Team SE-EDU      Since: Jun 2016      Licence: MIT

1. Introduction

Welcome to the SuperTA Developer Guide. This guide provides information to help you get started as a SuperTA contributor, allowing you to code, test and improve on the software without much hassle.

SuperTA is a desktop application for Teaching Assistants and Professors in NUS School of Computing. It provides a convenient, flexible and fast method to manage students and their tutorials. This software is also designed to have the Command Line Interface (CLI) to be the primary mode of input while the GUI is used for visual feedback to the user.

If you’re brand new to SuperTA and want to jump into code, start with Section 2, “Setting up”.

2. Setting up

2.1. Prerequisites

  1. JDK 9 or later

    JDK 10 on Windows will fail to run tests in headless mode due to a JavaFX bug. Windows developers are highly recommended to use JDK 9.

  2. IntelliJ IDE

    IntelliJ by default has Gradle and JavaFx plugins installed.
    Do not disable them. If you have disabled them, go to File > Settings > Plugins to re-enable them.

2.2. Setting up the project in your computer

  1. Fork this repo, and clone the fork to your computer

  2. Open IntelliJ (if you are not in the welcome screen, click File > Close Project to close the existing project dialog first)

  3. Set up the correct JDK version for Gradle

    1. Click Configure > Project Defaults > Project Structure

    2. Click New…​ and find the directory of the JDK

  4. Click Import Project

  5. Locate the build.gradle file and select it. Click OK

  6. Click Open as Project

  7. Click OK to accept the default settings

  8. Open a console and run the command gradlew processResources (Mac/Linux: ./gradlew processResources). It should finish with the BUILD SUCCESSFUL message.
    This will generate all resources required by the application and tests.

  9. Open XmlAdaptedStudent.java and MainWindow.java and check for any code errors

    1. Due to an ongoing issue with some of the newer versions of IntelliJ, code errors may be detected even if the project can be built and run successfully

    2. To resolve this, place your cursor over any of the code section highlighted in red. Press ALT+ENTER, and select Add '--add-modules=…​' to module compiler options for each error

  10. Repeat this for the test folder as well (e.g. check XmlUtilTest.java and HelpWindowTest.java for code errors, and if so, resolve it the same way)

2.3. Verifying the setup

  1. Run the seedu.superta.MainApp and try a few commands

  2. Run the tests to ensure they all pass.

2.4. Configurations to do before writing code

2.4.1. Configuring the coding style

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

  1. Go to File > Settings…​ (Windows/Linux), or IntelliJ IDEA > Preferences…​ (macOS)

  2. Select Editor > Code Style > Java

  3. Click on the Imports tab to set the order

    • For Class count to use import with '*' and Names count to use static import with '*': Set to 999 to prevent IntelliJ from contracting the import statements

    • For Import Layout: The order is import static all other imports, import java.*, import javax.*, import org.*, import com.*, import all other imports. Add a <blank line> between each import

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

2.4.2. Updating documentation to match your fork

After forking the repo, the documentation will still refer to the CS2103-AY1819S1-T16-2 repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to CS2103-AY1819S1-T16-2), you should do the following:

  1. Configure the site-wide documentation settings in build.gradle, such as the site-name, to suit your own project.

  2. Replace the URL in the attribute repoURL in DeveloperGuide.adoc and UserGuide.adoc with the URL of your fork.

2.4.3. Setting up CI

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

Coverage reporting could be useful for a team repository that hosts the final version but it is not that useful for your personal fork.

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

Having both Travis and AppVeyor ensures your App works on both Unix-based platforms and Windows-based platforms (Travis is Unix-based and AppVeyor is Windows-based)

2.4.4. Getting started with coding

When you are ready to start coding,

  1. Get some sense of the overall design by reading Section 3.1, “Architecture”.

  2. Take a look at [GetStartedProgramming].

3. Design

3.1. Architecture

Architecture
Figure 1. Architecture Diagram

The Architecture Diagram given above explains the high-level design of the App. Given below is a quick overview of each component.

The .pptx files used to create diagrams in this document can be found in the diagrams folder. To update a diagram, modify the diagram in the pptx file, select the objects of the diagram, and choose Save as picture.

Main has only one class called MainApp. It is responsible for,

  • At app launch: Initializes the components in the correct sequence, and connects them up with each other.

  • At shut down: Shuts down the components and invokes cleanup method where necessary.

Commons represents a collection of classes used by multiple other components. Two of those classes play important roles at the architecture level.

  • EventsCenter : This class (written using Google’s Event Bus library) is used by components to communicate with other components using events (i.e. a form of Event Driven design)

  • LogsCenter : Used by many classes to write log messages to the App’s log file.

The rest of the App consists of four components.

  • UI: The UI of the App.

  • Logic: The command executor.

  • Model: Holds the data of the App in-memory.

  • Storage: Reads data from, and writes data to, the hard disk.

Each of the four components

  • Defines its API in an interface with the same name as the Component.

  • Exposes its functionality using a {Component Name}Manager class.

For example, the Logic component (see the class diagram given below) defines it’s API in the Logic.java interface and exposes its functionality using the LogicManager.java class.

LogicClassDiagram
Figure 2. Class Diagram of the Logic Component

Events-Driven nature of the design

The Sequence Diagram below shows how the components interact for the scenario where the user issues the command delete-assignment as/lab1 tg/04a.

SDforDeleteAssignment
Figure 3. Component interactions for delete-assignment as/lab1 tg/04a command (part 1)
Note how the Model simply raises a SuperTaChangedEvent when the SuperTA client data is changed, instead of asking the Storage to save the updates to the hard disk.

The diagram below shows how the EventsCenter reacts to that event, which eventually results in the updates being saved to the hard disk and the status bar of the UI being updated to reflect the 'Last Updated' time.

SDforDeleteAssignmentEventHandling
Figure 4. Component interactions for delete-assignment as/lab1 tg/04a command (part 2)
Note how the event is propagated through the EventsCenter to the Storage and UI without Model having to be coupled to either of them. This is an example of how this Event Driven approach helps us reduce direct coupling between components.

The sections below give more details of each component.

3.2. UI component

UiClassDiagram
Figure 5. Structure of the UI Component

API : Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, StudentListPanel, StatusBarFooter etc. All these, including the MainWindow, inherit from the abstract UiPart class.

The UI component uses JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

  • Executes user commands using the Logic component.

  • Binds itself to some data in the Model so that the UI can auto-update when data in the Model change.

  • Responds to events raised from various parts of the App and updates the UI accordingly.

3.3. Logic component

LogicClassDiagram
Figure 6. Structure of the Logic Component

API : Logic.java

  1. Logic uses the SuperTaClientParser class to parse the user command.

  2. This results in a Command object which is executed by the LogicManager.

  3. The command execution can affect the Model (e.g. adding a student) and/or raise events.

  4. The result of the command execution is encapsulated as a CommandResult object which is passed back to the Ui.

Given below is the Sequence Diagram for interactions within the Logic component for the execute("delete assignment as/lab1 tg/04a") API call.

DeleteAssignmentSdForLogic
Figure 7. Interactions Inside the Logic Component for the delete-assignment as/lab1 tg/04a Command

3.4. Model component

ModelClassDiagram
Figure 8. Structure of the Model Component

API : Model.java

The Model,

  • stores a UserPref object that represents the user’s preferences.

  • stores the SuperTA client data.

  • exposes an unmodifiable ObservableList<Student>,ObservableList<Attendance> and ObservableList<TutorialGroup> that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.

  • does not depend on any of the other three components.

As a more OOP model, we can store a Tag list in SuperTaClient, which Student can reference. This would allow SuperTaClient to only require one Tag object per unique Tag, instead of each Student needing their own Tag object. An example of how such a model may look like is given below.

ModelClassBetterOopDiagram

3.5. Storage component

StorageClassDiagram
Figure 9. Structure of the Storage Component

API : Storage.java

The Storage component,

  • can save UserPref objects in json format and read it back.

  • can save the SuperTA client data in xml format and read it back.

3.6. TutorialGroupMaster Design

TutorialGroupMasterDiagram
Figure 10. Structure of the TutorialGroupMaster

API : TutorialGroupMaster.java

The TutorialGroupMaster,

  • stores all Unique Identifiers (UIDs) of TutorialGroup in a Set<String>.

  • stores all TutorialGroup instances that are present in the SuperTA client in a Map<String, TutorialGroup, which maps the ID of the TutorialGroup to the instance for fast lookup.

  • exposes an unmodifiable ObservableList<TutorialGroup> that can be 'observed', mirroring changes to the internal map.

  • Can propogate removal of Student instances to all TutorialGroup s.

  • does not depend on any other component to operate.

The TutorialGroupMaster handles generation of UIDs as well. If a TutorialGroup is inserted when some other TutorialGroup instance has the same ID, then TutorialGroupMaster will automatically generate a unique suffix and use that as the id of the inserted TutorialGroup. For example, the user tries to insert a TutorialGroup whose initial ID is 04a, but there is an existing TutorialGroup with that same ID. The TutorialGroupMaster will then generate a suffix for this new TutorialGroup. The new ID will look something like 04a-dusty123.

The TutorialGroupMaster is able to handle lookup of TutorialGroup by ID quickly because it stores TutorialGroup instances in a Map which has the TutorialGroup IDs as key values. This notion of a master is necessary so we can handle operations such as propagating Student deletions to every single TutorialGroup.

3.7. TutorialGroup Model

TutorialGroupDiagram
Figure 11. Structure of the TutorialGroup Component

API : TutorialGroup.java

The TutorialGroup model,

  • has a unique identifier.

  • has a name.

  • has a list of Student s that belong to it.

  • has a list of Assignment s that belong to it.

  • has a list of Session s that belong to it.

  • should only contain Student s that are in the main client.

The TutorialGroup model houses all other object instances that are crucial to the operation of the client. This is done because it makes logical sense - Student s, Assignment s, and Session s should belong to a TutorialGroup .
TutorialGroupObjectDiagram

This is an example of the use case of a TutorialGroup. In this object diagram, we have a TutorialGroup with the name Studio04A and the ID 04a. It holds lists of Student s, Assignment s, and Session s in its appropriate lists. Each entity is not coupled with each other - it uses the StudentId to find out which Student is associated with it. For example, The GradeEntry object composes of a StudentId object, which will allow other components to find out which is the underlying Student model with this StudentId. This is done so that we don’t have to update each entity with updated copies of a Student when the user triggers an update event.

3.7.1. Design Considerations

Aspect: Alternative Implementation Methods

  • Alternative 1: Store Assignment s, Session s, and Student s in a normalised manner - that is, the ModelManager would instead contain lists of all of these entities. Every TutorialGroup would then reference an identifier if it wanted a reference to that entity.

    • Pros: Any updates to an underlying model would be propagated to every TutorialGroup referencing it. Normalised data is also easier to reference. Future classes can also reference these with no problem.

    • Cons: This implementation will require additional layers of abstraction, and will require many changes to the model.

3.8. Common classes

Classes used by multiple components are in the seedu.superta.commons package.

4. Implementation

This section describes some noteworthy details on how certain features are implemented.

4.1. Undo/Redo feature

4.1.1. Current Implementation

The undo/redo mechanism is facilitated by VersionedSuperTaClient. It extends SuperTaClient with an undo/redo history, stored internally as an superTaClientStateList and currentStatePointer. Additionally, it implements the following operations:

  • VersionedSuperTaClient#commit() — Saves the current SuperTA client state in its history.

  • VersionedSuperTaClient#undo() — Restores the previous SuperTA client state from its history.

  • VersionedSuperTaClient#redo() — Restores a previously undone SuperTA client state from its history.

These operations are exposed in the Model interface as Model#commitSuperTaClient(), Model#undoSuperTaClient() and Model#redoSuperTaClient() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedSuperTaClient will be initialized with the initial SuperTA client state, and the currentStatePointer pointing to that single SuperTA client state.

UndoRedoStartingStateListDiagram

Step 2. The user executes delete 5 command to delete the 5th student in the SuperTA client. The delete command calls Model#commitSuperTaClient(), causing the modified state of the SuperTA client after the delete 5 command executes to be saved in the superTaClientStateList, and the currentStatePointer is shifted to the newly inserted SuperTA client state.

UndoRedoNewCommand1StateListDiagram

Step 3. The user executes add n/David …​ to add a new student. The add command also calls Model#commitSuperTaClient(), causing another modified SuperTA client state to be saved into the superTaClientStateList.

UndoRedoNewCommand2StateListDiagram
If a command fails its execution, it will not call Model#commitSuperTaClient(), so the SuperTA client state will not be saved into the superTaClientStateList.

Step 4. The user now decides that adding the student was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoSuperTaClient(), which will shift the currentStatePointer once to the left, pointing it to the previous SuperTA client state, and restores the SuperTA client to that state.

UndoRedoExecuteUndoStateListDiagram
If the currentStatePointer is at index 0, pointing to the initial SuperTA client state, then there are no previous SuperTA client states to restore. The undo command uses Model#canUndoSuperTaClient() to check if this is the case. If so, it will return an error to the user rather than attempting to perform the undo.

The following sequence diagram shows how the undo operation works:

UndoRedoSequenceDiagram

The redo command does the opposite — it calls Model#redoSuperTaClient(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the SuperTA client to that state.

If the currentStatePointer is at index superTaClientStateList.size() - 1, pointing to the latest SuperTA client state, then there are no undone SuperTA client states to restore. The redo command uses Model#canRedoSuperTaClient() to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo.

Step 5. The user then decides to execute the command list. Commands that do not modify the SuperTA client, such as list, will usually not call Model#commitSuperTaClient(), Model#undoSuperTaClient() or Model#redoSuperTaClient(). Thus, the superTaClientStateList remains unchanged.

UndoRedoNewCommand3StateListDiagram

Step 6. The user executes clear, which calls Model#commitAddressBook(). Since the currentStatePointer is not pointing at the end of the superTaClientStateList, all SuperTA client states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add n/David …​ command. This is the behavior that most modern desktop applications follow.

UndoRedoNewCommand4StateListDiagram

The following activity diagram summarizes what happens when a user executes a new command:

UndoRedoActivityDiagram

4.1.2. Design Considerations

Aspect: How undo & redo executes

  • Alternative 1 (current choice): Saves the entire SuperTA client.

    • Pros: Easy to implement.

    • Cons: May have performance issues in terms of memory usage.

  • Alternative 2: Individual command knows how to undo/redo by itself.

    • Pros: Will use less memory (e.g. for delete, just save the student being deleted).

    • Cons: We must ensure that the implementation of each individual command are correct.

Aspect: Data structure to support the undo/redo commands

  • Alternative 1 (current choice): Use a list to store the history of SuperTA client states.

    • Pros: Easy for new Computer Science student undergraduates to understand, who are likely to be the new incoming developers of our project.

    • Cons: Logic is duplicated twice. For example, when a new command is executed, we must remember to update both HistoryManager and VersionedSuperTaClient.

  • Alternative 2: Use HistoryManager for undo/redo

    • Pros: We do not need to maintain a separate list, and just reuse what is already in the codebase.

    • Cons: Requires dealing with commands that have already been undone: We must remember to skip these commands. Violates Single Responsibility Principle and Separation of Concerns as HistoryManager now needs to do two different things.

4.2. Delete Assignment feature

4.2.1. Current Implementation

The delete-assignment command is facilitated by the DeleteAssignmentCommand class. It extends the abstract class Command and is supported by DeleteAssignmentCommandParser, and changes made to the Model are done through Model#deleteAssignment().

The delete-assignment command is executed in the following way:

  1. LogicManager calls parseCommand() of SuperTaClientParser, with the user input as the argument.

  2. SuperTaClientParser invokes parse() of DeleteAssignmentCommandParser.

  3. If arguments are valid, parse extracts fromTutorialGroup and assToDelete strings to instantiate a DeleteAssignmentCommand.

  4. The DeleteAssignmentCommand is returned to LogicManager, which calls execute() on it.

  5. DeleteAssignment calls Model#deleteAssignment() using fromTutorialGroup and assToDelete.

The following is a sequence diagram of the delete-assignment command:

DeleteAssignmentSdForLogic

4.2.2. Design Considerations

Aspect: Implementation of DeleteAssignmentCommand

  • Alternative 1(current choice): Store the tutorial group ID and assignment title as String fields in DeleteAssignmentCommand.

    • Pros: Easy to implement. Does not require instantiating new TutorialGroup and Assignment objects to hold the String values.

    • Cons: Requires that the Model supports finding a tutorial group and assignment within Model#deleteAssignment().

  • Alternative 2: Wrap the tutorial group ID and assignment title in TutorialGroup and Assignment objects and store them as fields in DeleteAssignmentCommand.

    • Pros: Easy to compare between actual TutorialGroup and Assignment using equals().

    • Cons: Dependent on the overridden equals() method in the TutorialGroup and Assignment classes to work as intended.

4.3. Find feature

4.3.1. Current Implementation

The find command is facilitated by the FindCommand class. It extends the abstract class Command, and it is triggered when the user enters find into SuperTaClient.

The sequence diagram below shows the overview when FindCommand is called:

SDFindCommand

The FindCommand is implemented as follows:

  1. LogicManager is called to execute the entered argument.

  2. LogicManager calls SuperTaClientParser, and parses the argument through the method parseCommand().

  3. SuperTaClientParser calls its respective command parsers of the argument using parse(). In this case, the FindCommandParser is called.

  4. FindCommandParser will now parse the arguments and turn into name, phone, email and studentID predicates. These predicates will be passed to FindCommand.

  5. When LogicManager invokes execute(), FindCommand will call updateFilteredStudentList() to the model component and update the student list to the latest results.

4.3.2. Design Considerations

Aspect: How FindCommandParser parse predicates

  • Alternative 1 (current choice): Each parameter field (ie name, phone) are parsed into its respective predicates (ie. namePredicate, phonePredicate).

    • Pros: Easy to implement. Predicates are grouped into how they are parsed.

    • Cons: Less user-friendly. Users are required to remember the prefixes for each field.

  • Alternative 2: Parse all arguments into a general string, then search all the fields and stored into a main predicate.

    • Pros: More versatile and user-friendly. The string is able to search all the fields.

    • Cons: Slightly more tedious as compared to alternative 1. The general string needs to parse into respective field objects and predicates for each available parameter.

4.4. Update Assignment feature

4.4.1. Current Implementation

The update-assignment command is facilitated by UpdateAssignmentCommand class. It extends the abstract class command, and it is triggered when the user enters update-assignment into SuperTaClient. Actual changes of this command are made through Model#updateAssignment().

The UpdateAssignmentCommand is implemented as follows:

UpdateAssignmentCommand only works when there is an existing assignment in an existing tutorial group, and the updated assignment name is not the same as other existing assignment title. In this implementation, it is assumed that there is a valid tutorial group and a valid existing assignment.
SDUpdateAssignmentCommandLogic
Figure 12. Logic component of the Sequence Diagram for update-assignment command

  1. LogicManager is called to execute the entered argument.

  2. LogicManager calls SuperTaClientParser, and parses the argument through the method parseCommand().

  3. SuperTaClientParser calls its respective command parsers of the argument using parse(). In this case, the UpdateAssignmentCommandParser() is called.

  4. UpdatAassignmentCommandParser will now parse the arguments.

  5. UpdateAssignmentCommandParser will create a new UpdateAssignmentDescriptor and set the updated assignment details, which later will be passed to UpdateAssignmentCommand.

  6. When LogicManager invokes execute(), UpdateAssignmentCommand will call updateAssignment() to the model component.

SDUpdateAssignmentCommandModel
Figure 13. Model component of the Sequence Diagram for update-assignment command

  1. When updateAssignment() is called in ModelManager, it will retrieve tutorialGroup and assignment information from SuperTaClient and TutorialGroup respectively.

  2. After locating the specific assignment to be changed, ModelManager now calls updateAssignment() to UiqueAssignmentList to replace the old assignment details.

  3. Updated information will be returned to the logic component (as ‘updated’) in the above diagram.

4.4.2. Design Considerations

Aspect: Implementation of UpdateAssignmentDescriptor in UpdateAssignmentCommand

  • Alternative 1 (current choice): Use of UpdateAssignmentDescriptor in UpdateAssignmentCommand to store the updated assignment details.

    • Pros: Strengthen Single Responsibility Principle (SRP), as the UpdateAssignmentCommand will not need to check for differences between the old and updated assignment details.

    • Cons: May increase coupling. If the additional assignment details are added in in the future such as section maximum marks, UpdateAssignmentDescriptor have to change accordingly as well.

  • Alternative 2: Remove UpdateAssignmentDescriptor and parse updated assignment details as a new assignment.

    • Pros: Decreases coupling.

    • Cons: Harder to implement if user only indicate to update one field. (eg: update assignmentTitle only, while maxMarks stay the same). In this case, UpdateAssignmentCommand need to factor in the differences changed after the updated assignment details.

Aspect: Data structure of update-assignment in ModelManager

  • Alternative 1: Locate assignment from assignmentList, then delete old assignment and add updated assignment.

    • Pros: Easier to implement as it made use of other existing assignment commands such as addAssignment() and deleteAssignment(). No additional methods are needed for updateAssignment().

    • Cons: As each assignment contains a GradeBook which stores all student grades, deleting the old assignment and add a new assignment may risk of losing the existing GradeBook records. In addition, assignment index list may be affected after deletion as well.

  • Alternative 2 (current choice): Locate assignment from assignmentList and replace the old assignment with updated assignment details.

    • Pros: No risk of losing GradeBook records as only the assignmentTitle and maxMarks are being edited.

    • Cons: An additional method, updateAssignment() will be implemented instead.

4.5. Mark Attendance feature

4.5.1. Current Implementation

The mark-attendance command is facilitated by the MarkAttendanceCommand class. It extends the abstract class Command and is supported by MarkAttendanceCommandParser, and changes made to the Model are done through Model#markAttendance().

The mark-attendance command is executed in the following way:

  1. LogicManager calls parseCommand() of SuperTaClientParser, with the user input as the argument.

  2. SuperTaClientParser invokes parse() of MarkAttendanceCommandParser.

  3. If arguments are valid, parse extracts tutorialGroupId string, sessionName and set of studentId strings for parsing into a Session and Set<StudentId> to instantiate a MarkAttendanceCommand.

  4. The MarkAttendanceCommand is returned to LogicManager, which calls execute() on it.

  5. MarkAttendance calls Model#markAttendance() using tgtId, sessionName and studentIdSet.

The following sequence diagrams of the mark-attendance command shows the sequence flow from LogicManager to the ModelManager:

SDforMarkAttendance1

A more in-depth sequence diagram to illustrate how the Model executes the mark-attendance command:

SDforMarkAttendance2

From the in-depth sequence diagram:

  1. Model calls VersionedSuperTaClient#markAttendance, using tgtId, sessionName and studentIdSet.

  2. VersionedSuperTaClient self-invokes the method getTutorialGroup(tgId) to obtain the tutorial group specified.

  3. VersionedSuperTaClient then calls getSession(sessionName) in the TutorialGroup instance obtained previously.

  4. VersionedSuperTaClient then streams the set of student Ids obtained in studentIdSet, mapping them to new Attendance objects and collecting them as a list.

  5. Finally, the attendanceList obtained is streamed, with each Attendance object being added to the Session instance obtained in step 3.

4.5.2. Design Considerations

Aspect: Implementation of MarkAttendanceCommand

  • Alternative 1(current choice): Store the tutorial group ID as String field, session name as a Session object and student ids as a set of StudentIds in MarkAttendanceCommand.

    • Pros: Easy to implement, and parse, with existing parsers built in. Ensures that parsed Session and StudentId objects are valid and abide by constraints.

    • Cons: Requires Session and StudentId objects to be instantiated. Also depends on isSameSession() method and containsId() method in Session and UniqueStudentList respectively.

  • Alternative 2: Store all parameters of MarkAttendanceCommand as String objects, including StudentIds as a set of Strings.

    • Pros: Easy to implement, will be able to find session and set of student ids by comparing strings.

    • Cons: Cannot ensure parsed session names and student ids are correct, valid and fit constraints.

Aspect: Implementation of Attendance

  • Alternative 1(current choice): Store Attendance object with an encapsulated StudentId object and Presence enumeration.

    • Pros: StudentId is assured to be valid, while Presence will only be able to take fixed, constant values,

    • Cons: Requires a new Presence enumeration to be defined, instead of relying on simpler string values.

  • Alternative 2: Store presence of student as an integer or string value.

    • Pros: Easy to implement, no need to create additional enumeration.

    • Cons: Cannot ensure that only fixed, valid values will be used when creating Attendance objects.

4.6. Logging

We are using java.util.logging package for logging. The LogsCenter class is used to manage the logging levels and logging destinations.

  • The logging level can be controlled using the logLevel setting in the configuration file (See Section 4.7, “Configuration”)

  • The Logger for a class can be obtained using LogsCenter.getLogger(Class) which will log messages according to the specified logging level

  • Currently log messages are output through: Console and to a .log file.

Logging Levels

  • SEVERE : Critical problem detected which may possibly cause the termination of the application

  • WARNING : Can continue, but with caution

  • INFO : Information showing the noteworthy actions by the App

  • FINE : Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size

4.7. Configuration

Certain properties of the application can be controlled (e.g App name, logging level) through the configuration file (default: config.json).

5. Documentation

We use asciidoc for writing documentation.

We chose asciidoc over Markdown because asciidoc, although a bit more complex than Markdown, provides more flexibility in formatting.

5.1. Editing Documentation

See UsingGradle.adoc to learn how to render .adoc files locally to preview the end result of your edits. Alternatively, you can download the AsciiDoc plugin for IntelliJ, which allows you to preview the changes you have made to your .adoc files in real-time.

5.2. Publishing Documentation

See UsingTravis.adoc to learn how to deploy GitHub Pages using Travis.

5.3. Converting Documentation to PDF format

We use Google Chrome for converting documentation to PDF format, as Chrome’s PDF engine preserves hyperlinks used in webpages.

Here are the steps to convert the project documentation files to PDF format.

  1. Follow the instructions in UsingGradle.adoc to convert the AsciiDoc files in the docs/ directory to HTML format.

  2. Go to your generated HTML files in the build/docs folder, right click on them and select Open with → Google Chrome.

  3. Within Chrome, click on the Print option in Chrome’s menu.

  4. Set the destination to Save as PDF, then click Save to save a copy of the file in PDF format. For best results, use the settings indicated in the screenshot below.

chrome save as pdf
Figure 14. Saving documentation as PDF files in Chrome

5.4. Site-wide Documentation Settings

The build.gradle file specifies some project-specific asciidoc attributes which affects how all documentation files within this project are rendered.

Attributes left unset in the build.gradle file will use their default value, if any.
Table 1. List of site-wide attributes
Attribute name Description Default value

site-name

The name of the website. If set, the name will be displayed near the top of the page.

not set

site-githuburl

URL to the site’s repository on GitHub. Setting this will add a "View on GitHub" link in the navigation bar.

not set

site-seedu

Define this attribute if the project is an official SE-EDU project. This will render the SE-EDU navigation bar at the top of the page, and add some SE-EDU-specific navigation items.

not set

5.5. Per-file Documentation Settings

Each .adoc file may also specify some file-specific asciidoc attributes which affects how the file is rendered.

Asciidoctor’s built-in attributes may be specified and used as well.

Attributes left unset in .adoc files will use their default value, if any.
Table 2. List of per-file attributes, excluding Asciidoctor’s built-in attributes
Attribute name Description Default value

site-section

Site section that the document belongs to. This will cause the associated item in the navigation bar to be highlighted. One of: UserGuide, DeveloperGuide, AboutUs, ContactUs

* Official SE-EDU projects only

not set

no-site-header

Set this attribute to remove the site navigation bar.

not set

5.6. Site Template

The files in docs/stylesheets are the CSS stylesheets of the site. You can modify them to change some properties of the site’s design.

The files in docs/templates controls the rendering of .adoc files into HTML5. These template files are written in a mixture of Ruby and Slim.

Modifying the template files in docs/templates requires some knowledge and experience with Ruby and Asciidoctor’s API. You should only modify them if you need greater control over the site’s layout than what stylesheets can provide. The SE-EDU team does not provide support for modified template files.

6. Testing

6.1. Running Tests

There are three ways to run tests.

The most reliable way to run tests is the 3rd one. The first two methods might fail some GUI tests due to platform/resolution-specific idiosyncrasies.

Method 1: Using IntelliJ JUnit test runner

  • To run all tests, right-click on the src/test/java folder and choose Run 'All Tests'

  • To run a subset of tests, you can right-click on a test package, test class, or a test and choose Run 'ABC'

Method 2: Using Gradle

  • Open a console and run the command gradlew clean allTests (Mac/Linux: ./gradlew clean allTests)

See UsingGradle.adoc for more info on how to run tests using Gradle.

Method 3: Using Gradle (headless)

Thanks to the TestFX library we use, our GUI tests can be run in the headless mode. In the headless mode, GUI tests do not show up on the screen. That means the developer can do other things on the Computer while the tests are running.

To run tests in headless mode, open a console and run the command gradlew clean headless allTests (Mac/Linux: ./gradlew clean headless allTests)

6.2. Types of tests

We have two types of tests:

  1. GUI Tests - These are tests involving the GUI. They include,

    1. System Tests that test the entire App by simulating user actions on the GUI. These are in the systemtests package.

    2. Unit tests that test the individual components. These are in seedu.superta.ui package.

  2. Non-GUI Tests - These are tests not involving the GUI. They include,

    1. Unit tests targeting the lowest level methods/classes.
      e.g. seedu.superta.commons.StringUtilTest

    2. Integration tests that are checking the integration of multiple code units (those code units are assumed to be working).
      e.g. seedu.superta.storage.StorageManagerTest

    3. Hybrids of unit and integration tests. These test are checking multiple code units as well as how the are connected together.
      e.g. seedu.superta.logic.LogicManagerTest

6.3. Troubleshooting Testing

Problem: HelpWindowTest fails with a NullPointerException.

  • Reason: One of its dependencies, HelpWindow.html in src/main/resources/docs is missing.

  • Solution: Execute Gradle task processResources.

7. Dev Ops

7.1. Build Automation

See UsingGradle.adoc to learn how to use Gradle for build automation.

7.2. Continuous Integration

We use Travis CI and AppVeyor to perform Continuous Integration on our projects. See UsingTravis.adoc and UsingAppVeyor.adoc for more details.

7.3. Coverage Reporting

We use Coveralls to track the code coverage of our projects. See UsingCoveralls.adoc for more details.

7.4. Documentation Previews

When a pull request has changes to asciidoc files, you can use Netlify to see a preview of how the HTML version of those asciidoc files will look like when the pull request is merged. See UsingNetlify.adoc for more details.

7.5. Making a Release

Here are the steps to create a new release.

  1. Update the version number in MainApp.java.

  2. Generate a JAR file using Gradle.

  3. Tag the repo with the version number. e.g. v0.1

  4. Create a new release using GitHub and upload the JAR file you created.

7.6. Managing Dependencies

A project often depends on third-party libraries. For example, SuperTA depends on the Jackson library for XML parsing. Managing these dependencies can be automated using Gradle. For example, Gradle can download the dependencies automatically, which is better than these alternatives.
a. Include those libraries in the repo (this bloats the repo size)
b. Require developers to download those libraries manually (this creates extra work for developers)

Appendix A: Product Scope

Target user profile:

  • TAs and Profs in SoC

  • has a need to manage a significant number of students

  • keeps track of student performance in tutorials

  • prefer desktop apps over other types

  • can type fast

  • prefers typing over mouse input

  • is reasonably comfortable using CLI apps

Value proposition:

  • Current situation:

    • TAs use IVLE, excel spreadsheets and many other systems to keep track of students performances, class participation and other information

    • Difficult to organize multitude of information

    • Hard to share data with other TAs, when they could be building on pre-existing data.

  • Proposed solution:

    • Central management system to keep track of students performances, tutorial attendance

    • Provide a platform for Tutors/TAs to better keep track of individual students and provide help early

Appendix B: User Stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Priority As a …​ I want to …​ So that I can…​

* * *

TA

see usage instructions

refer to instructions when I forget how to use the App

* * *

TA

add a new student

* * *

TA

edit a student

keep their details updated

* * *

TA

view a student

know the student’s details in a glance

* * *

TA

delete a student

remove entries that I no longer need

* * *

TA

find a student by name

locate details of students without having to go through the entire list

* * *

TA

find a student by matriculation number

locate details of persons without having to remember his/her name

* * *

TA

give feedback for my students

update additional information about the student

* * *

TA

create a tutorial group

categorize them into groups

* * *

TA

delete a tutorial group

remove them when I am no longer teaching in it

* * *

TA

add a student to a tutorial group

* * *

TA

delete a student from a tutorial group

see students in a specific tutorial group

* * *

TA

add attendance for my students

know whether my students are coming to tutorials

* * *

TA

delete attendance for my students

remove entries that I no longer need

* * *

TA

add an assignment to tutorial group

track the assignments

* * *

TA

delete an assignment to tutorial group

remove entries that I no longer need

* * *

TA

add marks to assignments

track their marks

* * *

TA

edit marks in assignments

change their marks

* * *

TA

sort students in order of their grades for a specific assignment

know who is/is not performing well

* *

TA

view the performance of my students over time through visual aids

easily view their progress at a glance

* *

TA

get recommendations on my teaching style

improve or change my teaching style

* *

TA

data trending of the performance of my students

track the progress of the students

* *

TA

plan consultations with students through a calendar system

better manage my time and the learning of the students

* *

TA

get suggestions on how to cater my teaching style to a specific student

teach that student better

* *

TA

flag a student that needs help

easily filter out the students that need help

* *

TA

plan non-clashing consultation sessions with students

reduce tht time needed to find a suitable date and time and better manage my schedule

* *

Prof/TA

access the academic records of my students with a secure password

prevent leaking of personal data

*

TA

share student records with other TAs

build on pre-existing data about the student

*

TA

receive student records from other TAs

understand my students better

*

TA

send emails to tutorial groups

relay important information to my students

*

TA

export student data to a CSV/PDF

easily share the data with related parties

*

Student

feedback to my TAs about their teaching style

learn better during classes

{More to be added}

Appendix C: Use Cases

(For all use cases, the System is the SuperTA Client and the User is TA.)

UC01 - Delete student

MSS:

  1. User requests to list students

  2. System shows a list of students

  3. User requests to delete a specific student in the list

  4. System deletes the student

    Use case ends.

Extensions:

  • 1a. The list is empty.

  • Use case ends.

  • 2a. The given index is invalid.

    • 2a1. System shows an error message.

      Use case resumes at step 2.

UC02 - Find student

MSS:

  1. User requests to find students using prefix and keywords

  2. System finds the student who information matched with the keywords

    Use case ends.

Extensions:

  • 1a. Prefix entered is not supported by find command

    • 1a1. System shows an error message.

  • 2a. None of the student matched the keywords provided by user

    • 2a1. No students will be listed.

UC03 - Add Tutorial Group

MSS:

  1. User clicks “Add Tutorial Group” button or enters command “add [tg/[NAME]] *[s/[STUDENT-ID]]”

  2. The tutorial group is created.

    Use case ends.

Extensions:

  • 1a. User enters invalid student details.

    • 1a1. System prompt user invalid student details entered.

    • 1a2. User re-enter student details.

      Use case resumes at step 2.

UC04 - Grade Assignment

MSS:

  1. User views a tutorial group.

  2. System displays the tutorial group.

  3. User creates assignment in tutorial group.

  4. System creates assignment.

  5. User enters grade of student to be graded for an assignment.

  6. System grades the assignment for the student.

    Use case ends.

Extensions:

  • 1a. User enters invalid tutorial group ID.

    • 1a1. System displays an error message.

      Use case resumes at step 1.

  • 3a. User enters invalid details for new assignment.

    • 3a1. System displays an error message.

      Use case resumes at step 3.

  • 5a. User enters invalid grade/student/assignment/tutorial group.

    • 5a1. System displays an error message.

      Use case resumes at step 5.

UC05 - Mark Attendance

MSS:

  1. User creates attendance session in tutorial group.

  2. System creates attendance session.

  3. User enters ID for student to mark attendance for the session.

  4. System marks student’s attendance for the session.

    Use case ends.

Extensions:

  • 1a. User enters invalid details for new attendance session.

    • 1a1. System displays an error message.

      Use case resumes at step 1.

  • 3a. User enters invalid student/session.

    • 3a1. System displays an error message.

      Use case resumes at step 3.

UC06 - Add feedback for student

MSS:

  1. User enters feedback for student.

  2. System creates feedback for student.

    Use case ends.

Extensions:

  • 1a. User enters invalid student/empty feedback.

    • 1a1. System displays an error message.

      Use case resumes at step 1.

{More to be added}

Appendix D: Non Functional Requirements

  1. The client should work without an Internet connection.

  2. The client should be able to be used by a first-timer without having to refer to the documentation all the time.

  3. The program should be responsive to the user’s input and display the results fast (<3s).

  4. The project is expected to adhere to semantic versioning.

  5. The client should not need to do syncing over the Internet.

  6. The codebase should have high code coverage (90%).

  7. The codebase should adhere to the Google Java style guide.

  8. The codebase should use Continuous Integration (CI).

  9. The master branch should always be functional.

{More to be added}

Appendix E: Glossary

SoC

School of Computing. A term used loosely for:

  1. anyone or anything that has to do with computing

  2. the building in NUS.

TA

Teaching Assistant. An individual, usually an SoC undergraduate, who is responsible for tutorial sessions in a given module.

Prof

Professor. An individual who teaches SoC modules.

Appendix F: Instructions for Manual Testing

Given below are instructions to test the app manually.

These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

F.1. Launch and Shutdown

  1. Initial launch

    1. Download the jar file and copy into an empty folder

    2. Double-click the jar file
      Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.

  2. Saving window preferences

    1. Resize the window to an optimum size. Move the window to a different location. Close the window.

    2. Re-launch the app by double-clicking the jar file.
      Expected: The most recent window size and location is retained.

F.2. Deleting a student

  1. Deleting a student while all students are listed

    1. Prerequisites: List all students using the list command. Multiple students in the list.

    2. Test case: delete 1
      Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated.

    3. Test case: delete 0
      Expected: No student is deleted. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect delete commands to try: delete, delete x (where x is larger than the list size)
      Expected: Similar to previous.

F.3. Finding a student

  1. Finding a student while all students are listed

    1. Test case: find n/john
      Expected: All students with name john will be on the list. Since it is case-insensitive, variations such as ‘John’ or ‘joHn’ will appear on the filtered list as well.

    2. Test case: find n/john mary
      Expected: All students with name john or ‘mary’ will be on the list. Similar to a, case-insensitive variations will appear on the filtered list.

    3. Test case: find p/91234567 id/A0123456T
      Expected: All students with phone number 91234567 or with student ID A0123456T will appear on the filtered list.

    4. Other than the indicated prefixes (n/, p/, ‘e/’, ‘id/’), any other prefixes (ie. tg/, ‘m/`) will show an invalid command format error message.

F.4. Creating a Tutorial Group

  1. Creating a tutorial group

    1. Prerequisites: List all tutorial groups using the list-tutorial-groups command.

    2. Test case: create-tutorial-group id/04a n/Test
      Expected: A new tutorial group with the id 04a and the name Test is created, and the list view is updated.

    3. Test case: Duplicate ID - create-tutorial-group id/04a n/Test
      In this test case, the id argument has to be an id that already exists in the memory. For example, you can run the above test case with the exact same arguments again. Expected: A new tutorial group with a different ID is created. The new ID has a random suffix appended to it. For example, if you run create-tutorial-group id/04a n/Test twice, the second tutorial group will have an ID that looks like 04a-stormy492.

F.5. Deleting a Tutorial Group

  1. Deleting a tutorial group

    1. Prerequisites: Have a tutorial group with an ID of 04a in the memory.
      View the tutorial group using the view-tutorial-group id/04a command.

    2. Test case: delete-tutorial-group id/04a
      Expected: The tutorial group is deleted. The UI shows [Deleted] next to the tutorial group name.

F.6. Creating an attendance session

  1. Creating an attendance session

    1. Prerequisites: Have one tutorial group with an ID of 04a.
      View the tutorial group using the view-tutorial-group id/04a command.

    2. Test case: create-attendance tg/04a n/W4 Tutorial
      Expected: An attendance session should be created. If you are on the detailed tutorial group screen, the UI should update accordingly.

    3. Test case: create-attendance tg/05a n/W4 Tutorial
      Expected: An error message should be displayed, saying that there is no such tutorial group.

    4. Test case: create-attendance tg/04a n/W4 Tutorial
      Expected: An error message should be displayed, saying that the attendance session already exists in the tutorial group.

F.7. Marking an attendance

  1. Marking an attendance

    1. Prerequisites: Have one tutorial group with an ID of 04a, an attendance session with name of W4 Tutorial and 3 students with student IDs A0166733Y, A0123456Y and A0144582N in the tutorial group.
      View the session in the tutorial group using the view-session tg/04a n/W4 Tutorial command.

    2. Test case: mark-attendance tg/04a n/W4 Tutorial st/A0166733Y
      Expected: The student with id A0166733Y should now be in the 'Attended' column.

    3. Test case: mark-attendance tg/04a n/W4 Tutorial st/A0123456Y st/A0144582N
      Expected: Both students with ids A0123456Y and A0144582N should now be in the 'Attended' column, as mark-attendance supports marking multiple students.

    4. Test case: Duplicate ID - mark-attendance tg/04a n/W4 Tutorial st/A0166733Y
      Expected: An error message should be displayed, saying that the student’s attendance is already marked.

    5. Test case: mark-attendance tg/05a n/W4 Tutorial st/A0166733Y
      Expected: An error message should be displayed, saying that there is no such tutorial group.

    6. Test case: mark-attendance tg/04a n/W4 Lab st/A0166733Y
      Expected: An error message should be displayed, saying that the session does not exist.

    7. Test case: mark-attendance tg/04a n/W4 Tutorial st/A1234560T
      Expected: An error message should be displayed, saying that the student is not in the tutorial group.

F.8. Creating an assignment

  1. Creating an assignment

    1. Prerequisites: Have one tutorial group with an ID of 04a.
      View the tutorial group using the view-tutorial-group id/04a command.

    2. Test case: create-assignment tg/04a n/lab1 m/40.0
      Expected: An assignment should be created on the screen.

    3. Test case: create-assignment tg/05a n/lab1 m/40.0
      Expected: An error message should be displayed, saying that there is no such tutorial group.

    4. Test case: create-assignment tg/04a n/lab1 m/test
      Expected: An error message should be displayed, saying that maximum marks should be a valid floating point number.

    5. Test case: create-assignment tg/04a n/lab1 m/-1
      Expected: An error message should be displayed, saying that the maximum marks should be more than 0.

F.9. Grading a student

  1. Grading a student

    1. Prerequisites: Have one tutorial group with an ID of 04a, and an assignment that belongs to it with the name lab1 with a maximum mark of 40.0. Also, a student with a student ID of A0166733Y should be added to the tutorial group.
      View the assignment in the tutorial group using the view-assignment tg/04a as/lab1 command.

    2. Test case: grade tg/04a st/A0166733Y as/lab1 m/35.0
      Expected: The student gets graded 35.0 out of 40.0 marks. If you are in the detailed tutorial group or assignment screen, the UI should be updated accordingly.

    3. Test case: grade tg/04a st/A0166733Y as/lab1 m/40.1
      Expected: An error message should be shown in the status message, because 40.1 is greater than the maximum marks of lab1.

    4. Test case: grade tg/04a st/A0166733Y as/lab1 m/-1
      Expected: An error message will be shown, since negative marks are invalid.

    5. Test case: grade tg/05a st/A0166733Y as/lab1 m/30
      Expected: An error message showing that there is no such tutorial group.

    6. Test case: grade tg/04a st/A0123456T as/lab1 m/30
      Expected: An error message showing that there is no such student in this tutorial group. You can also try this when there is a student in the main directory with this ID, but this student is not added to the tutorial group.

    7. Test case: grade tg/04a st/A0166733Y as/lab2 m/30
      Expected: An error message showing that there is no such assignment.

F.10. Updating an assignment detail

  1. Update an assignment detail

    1. Prerequisites: Have one tutorial group with an ID of 04a.
      View the tutorial group using the view-tutorial-group id/04a command.
      Have an assignment title named lab1 with a maximum mark of 40.0.
      Have an assignment title named lab3 with a maximum mark of 50.0.

    2. Test case: update-assignment tg/04a as/lab1 new_as/lab2
      Expected: Assignment lab1 name should now be changed to lab2 under the Assignments UI panel. Maximum marks should be maintained at 40.0 marks.

    3. Test case: update-assignment tg/04a as/lab2 new_m/50.0
      Expected: Assignment lab2 maximum marks should be changed from 40.0 marks to 50.0 marks under the Assignments UI panel.

    4. Test case: update-assignment tg/04a as/lab2 new_m/lab3
      Expected: An error message should be displayed, showing that assignment name already exists in the database.

    5. Test case: update-assignment tg/04a as/lab4 new_m/lab5
      Expected: An error message should be displayed, showing that assignment does not exist.

F.11. Giving feedback to a student

  1. Giving feedback to a student

    1. Prerequisites: Have a student with student id of A0166733Y
      View the student using the view id/A0166733Y command.

    2. Test case: feedback id/A0166733Y f/Is generally attentive during class.
      Expected: The student gets a feedback on the student profile.

    3. Test case: feedback id/A0123456T f/Is generally attentive during class.
      Expected: An error message showing that there is no such student.

{ more test cases …​ }