[CS2113T-F12-3] Teaching Assistant's Assistant #46
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,38 +1,231 @@ | ||
| # Developer Guide | ||
| * [Acknowledgements](#acknowledgements) | ||
| * [Design](#design) | ||
| * [Implementation](#implementation) | ||
| * [Add Module](#add-module) | ||
| * [Add Student](#add-student) | ||
| * [Add Assessment](#add-assessment) | ||
| * [Set Marks](#set-marks) | ||
| * [Set Attendance](#set-attendance) | ||
| * [Project scope](#product-scope) | ||
| * [User Stories](#user-stories) | ||
| * [Non-Functional Requirements](#non-functional-requirements) | ||
| * [Glossary](#glossary) | ||
|
|
||
| ## Acknowledgements | ||
|
|
||
| {list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the original source as well} | ||
|
|
||
| ## Design | ||
| ### Architecture | ||
|  | ||
|
|
||
|
|
||
| The _Architecture Diagram_ shown above illustrates the high-level design of the Application. | ||
|
|
||
| **Overview of components** | ||
| * `Main` | ||
| * On app launch: Creates and runs an instance of `Taa`. | ||
| * `UI` | ||
| * Handles UI operations. | ||
| * `Taa` | ||
|
There was a problem hiding this comment. The sequence diagram of TAA has a problem:
The activation bar of Taa should be closed |
||
| * On creation: Initializes the `UI` and `Storage` components. | ||
| * On run: Loads persistent data from `Storage`, receives user input from `UI`, and uses `Parser` to parse the user input. | ||
| * `Parser` | ||
| * Handles input parsing and determines which command to run. | ||
| * `Command` | ||
|
There was a problem hiding this comment. Would it be better to add function notation?
|
||
| * Defines how a command is to be executed. | ||
| * `ModuleList` | ||
| * Contains a list of `Module` objects currently being managed by the app. | ||
| * `Util` | ||
|
There was a problem hiding this comment. You could further explain in-depth how the util component works. This will help your users get an idea of what util can be used for when they work on your code. |
||
| * Contains useful methods (e.g. Check if a string is integer/double, convert string to integer/double). | ||
| * `Storage` | ||
|
There was a problem hiding this comment. Youd could add UML diagrams for the Storage function. This will enable your users to understand how data is written and stored by TAA as well as how it is accessed an read as inputs. |
||
| * Handles data storage operations (e.g. Reading from and writing to data file). | ||
|
There was a problem hiding this comment.
|
||
|
|
||
| <br> | ||
|
|
||
| **Interaction between components** | ||
|  | ||
|
There was a problem hiding this comment. It would be better to add the notation of the grey file icon |
||
|
|
||
| The _Architecture Sequence Diagram_ shown above shows how the components usually interact with each other. | ||
|
|
||
| ## Implementation | ||
| ### Add Module | ||
| The sequence diagram shown below illustrates how the `add_module` command works: | ||
|  | ||
|
There was a problem hiding this comment. Nice description for the steps, but maybe you can add numbering in the diagram and link it to the steps. There was a problem hiding this comment.
|
||
|
|
||
| Steps: | ||
| 1. The `Taa` instance reads in a user input through the `Ui.getUserInput()` method. | ||
| 2. The user input is then parsed using the `Parser.parseUserInput(userInput:String)` static method and a `Command` object | ||
| is returned. | ||
| 3. `AddModuleCommand.checkArguments()` is then called to check if the arguments are valid. | ||
| 4. After checking the arguments, `Command.execute(moduleList:ModuleList, ui:Ui, storage:Storage)` will be called. A new | ||
| `Module` object is created and the `ModuleList.addModule(module:Module)` method is invoked to add the `Module` | ||
| object into the list of modules. | ||
| 5. Lastly, a message indicating that the module has been added will be printed out. | ||
|
|
||
| <br> | ||
|
|
||
| ### Add Student | ||
| The add student mechanism is facilitated by `AddStudentCommand`. It extends `Command` and uses `StudentList` which | ||
| stores student internally as an ArrayList `students`. | ||
| <br> | ||
|
|
||
| `AddStudentCommand` implements the following methods: | ||
| * `AddStudentCommand#execute(moduleList:ModuleList, ui:Ui, storage:Storage)` - Performs operations for the command. | ||
|
|
||
| `StudentList` implements the following methods: | ||
| * `StudentList#getSize()` - Returns the no. of students currently in the list. | ||
| * `StudentList#getStudents()` - Returns an ArrayList containing all the students. | ||
| * `StudentList#getStudentAt(index:int)` - Returns a student with the particular index. | ||
| * `StudentList#isValidIndex(index:int)` - Checks if an index is valid w.r.t the `students` ArrayList. | ||
| * `StudentList#addStudent(student:Student)` - Adds a student to the `students` ArrayList. | ||
| * `StudentList#deleteStudent(index:int)` - Deletes the `student` object at the specified `index` within the `students` | ||
| ArrayList. | ||
| * `StudentList#findStudent(keyword:String)` - Returns an ArrayList of students containing the keyword | ||
|
|
||
| The sequence diagram shown below illustrates how the `add_student` command works: | ||
|  | ||
|
There was a problem hiding this comment. You could maybe add numbering in the diagram so that you can link the steps to the diagram to make it more clear. There was a problem hiding this comment. Perhaps you could explain step by step how the add_student command is being parsed and saved. There was a problem hiding this comment. You could perhaps split up the uml diagram to include sub parts of the e.g. focuses on the logic only so that the uml diagram could be bigger and clearer. ref: https://se-education.org/addressbook-level3/DeveloperGuide.html |
||
|
|
||
| Below is an example scenario of how the add student feature behaves at each step:<br> | ||
| * Step 1 - The user executes `add_student c/CS2113T i/a0217978j n/jonny` to add a student. The `add_student` command | ||
| calls the `AddStudentCommand#execute` method. Within `AddStudentCommand#execute`, `ModuleList#getModule("CS2113T")` is | ||
| called to ensure that there is an existing module with code `CS2113T`. | ||
| * Step 2 - If an existing module with code `CS2113T` is found, a new `Student` object with id and name set to | ||
| `a0217978j` and `jonny` respectively. Then, `StudentList#addModule` is called to add the newly created `Student` | ||
| object into the `students` ArrayList within `StudentList`. | ||
|
|
||
| <br> | ||
|
|
||
| ### Add Assessment | ||
|
There was a problem hiding this comment. The description for the implementation of Assessment tends to be a bit wordy and hard to follow. To make it easier for your users to understand this command function you could add an UML sequence diagram like the other commands. There was a problem hiding this comment. Neatness/correctness: |
||
| The add assessment mechanism is facilitated by `AddAssessmentCommand`. It extends `Command` and uses `AssessmentList` | ||
| which stores assessment internally as an ArrayList `assessments`.<br> | ||
|
|
||
| `AddAssessmentCommand` implements the following methods: | ||
| * `AddAssessmentCommand#execute(moduleList:ModuleList, ui:Ui, storage:Storage)` - Performs operations for the command. | ||
|
|
||
| `AssessmentList` implements the following methods: | ||
| * `AssessmentList#getSize()` - Returns the no. of assessments currently in the list. | ||
| * `AssessmentList#getAssessments()` - Returns an ArrayList containing all the assessments. | ||
| * `AssessmentList#getAssessment(assessmentName:String)` - Returns an assessment with a particular name specified by the | ||
| user. | ||
| * `AssessmentList#addAssessment(assessment:Assessment)` - Adds an assessment to the `assessments` ArrayList. | ||
| * `AssessmentList#deleteAssessment(assessmentName:String)` - Deletes an assessment with the name specified by the user | ||
| from the `assessments` ArrayList. | ||
|
|
||
| The sequence diagram shown below illustrates how the `add_assessment` command works: | ||
|  | ||
|
There was a problem hiding this comment.
|
||
|
|
||
| Below is an example scenario of how the add assessment feature behaves at each step: | ||
| * Step 1 - The user executes `add_assessment c/cs2113t n/midterms m/20 w/10` to add an assessment. The `add_assessment` | ||
| command calls the `AddAssessmentCommand#execute` method. Within `AddAssessmentCommand#execute`, | ||
| `ModuleList#getModuleWithCode("cs2113t")` is called to ensure that there is an existing module with code `cs2113t`. | ||
| * Step 2 - If an existing module with code `cs2113t` is found, the `MAXIMUM_MARKS` and `WEIGHTAGE` arguments are checked | ||
| to ensure that they are valid. | ||
| * Step 3 - If the `MAXIMUM_MARKS` and `WEIGHTAGE` arguments are valid, a new `Assessment` object with name, | ||
| maximum marks and weightage set to `midterms`, `20` and `10` respectively is created under the existing `Module` with | ||
| code `cs2113t`. Then, `AssessmentList#addAssessment` is called to add the newly created `Assessment` object into the | ||
| `assessments` ArrayList within `AssessmentList`. | ||
| * Step 4 - Within `AssessmentList#addAssessment`, the name of the newly created `Assessment` object is checked to ensure | ||
| there is no existing assessment with name `midterms`. At the same time, the weightage of the newly created | ||
| `Assessment` object is also checked to ensure that the total weightage of the assessments in the `cs2113t` module | ||
| will not exceed 100 with the addition of the weightage of the newly created `Assessment` object. | ||
| * Step 5 - If the name and weightage of the newly created `Assessment` object are valid, the newly created `Assessment` | ||
| object is added into the `assessments` ArrayList within `AssessmentList`. | ||
|
|
||
| <br> | ||
|
|
||
| ### Set Marks | ||
|
There was a problem hiding this comment. You could add an example scenario like the other commands so that it is easier for your users to understand how this command works. There was a problem hiding this comment. Use of examples: Not enough or too many examples e.g., sample inputs/outputs |
||
| The sequence diagram shown below illustrates how the `set_mark` command works: | ||
|  | ||
|
There was a problem hiding this comment. You could maybe also add numbering for the diagram so that readers can easily refer to the diagram from the steps. |
||
|
|
||
| Steps: | ||
| 1. The `Taa` instance reads in a user input through the `Ui.getUserInput()` method. | ||
| 2. The user input is then parsed using the `Parser.parseUserInput(userInput:String)` static method and a `Command` object | ||
| is returned. | ||
| 3. `AddModuleCommand.checkArguments()` is then called to check if the arguments are valid. | ||
| 4. After checking the arguments, `Command.execute(moduleList:ModuleList, ui:Ui, storage:Storage)` will be called. | ||
| 5. The `module:Module` which the student and assessment belongs to is retrieved with | ||
| `getModuleWithCode(moduleCode:String)`. | ||
| 6. Using `module:Module`, we are able to get the `studentList:StudentList` and `assessmentList:AssessmentList`. | ||
| 7. The `student:Student` and `assessment:Assessment` are then retrieved from their lists using | ||
| `getStudentAt(studentIndex:Integer)` and `getAssessment(assessmentName:String)` respectively. | ||
| 8. Finally, `setMarks(assessmentName:String, marks:Double)` is called to set the marks of the assessment in the | ||
| student's `results` HashMap. | ||
| 9. A message will then be printed out to indicate to the user that the marks have been set successfully. | ||
|
|
||
|
|
||
| ### Set Attendance | ||
|
There was a problem hiding this comment. You could use an UML sequence diagram here as well for easier reference of how this command function works for your users. |
||
| The set attendance mechanism is facilitated by SetAttendanceCommand. It extends `Command` and | ||
| uses `AttendanceList` which stores a student's lessons attendance as an | ||
| ArrayList `attendances`. | ||
| <br> | ||
|
|
||
| `SetAttendanceCommand` implements the following methods: | ||
| * `SetAttendanceCommand#execute(moduleList:ModuleList, ui:Ui, storage:Storage)` - Performs operations for the command. | ||
|
|
||
| `AttendanceList` implements the following methods: | ||
| * `AttendanceList#getSize()` - Returns the no. of attendance currently in the list. | ||
| * `AttendanceList#getAttendances()` - Returns an ArrayList containing all the attendances. | ||
| * `AttendanceList#getAttendance(lessonNumber:String)` - Returns an attendance with a particular lesson number. | ||
| * `AttendanceList#isValidIndex(index:int)` - Checks if an index is valid w.r.t the `attendances` ArrayList. | ||
| * `AttendanceList#addAttendance(attendance:Attendance)` - Adds an attendance to the `attendances` ArrayList. | ||
| * `AttendnaceList#getAttendnaceIndex(lessonNumInput:String)` - Returns the attendance index in the `attendances` | ||
| ArrayList. | ||
| * `AttendanceList#deleteAttendance(lessonNumInput:String)` - Deletes an attendance with a particular lesson number. | ||
| * `AttendanceList#sortAttendances` - Sorts the attendance in the `attendances` ArrayList in ascending order based on | ||
|
There was a problem hiding this comment. Maybe can consider putting these on a table as they are a bit too hard to read. |
||
| lesson number. | ||
|
|
||
| Below is an example scenario of how the set attendance feature behaves at each step: | ||
|
There was a problem hiding this comment. The steps here look a bit chunky, maybe you could split them up into more steps which could help readers digest it better. |
||
| * Step 1 - The user executes `set_attendance c/CS2113T s/1 l/1 p/1` to set an attendance to `Present` for student at | ||
|
There was a problem hiding this comment. Neatness/correctness: perhaps some more spacing at a minimum |
||
| index `1`, lesson number `1` to set a student's attendance for a lesson. The `set_attendance` command calls the | ||
| `SetAttendanceCommand#execute` method. Within `SetAttendanceCommand#execute`, `AttendanceList#getAttendance("1")` is | ||
| called to ensure that there is no existing attendance with the | ||
| lesson number `1`for student at index `1`. | ||
| * Step 2 - If no existing attendance object with lesson number `1` for student at index `1` is found, a new | ||
| `Attendance` object | ||
| with lesson number `1` and attendance record `Present` is set as its lesson number and attendance record respectively. | ||
| Then, `AttendanceList#addAttendance` is called to add the newly created `Attendance` object into the `attendances` | ||
| ArrayList within `AttendanceList`. | ||
|
|
||
| <br> | ||
|
|
||
| ## Product scope | ||
| ### Target user profile | ||
|
|
||
| * Teaching assistant who has a need to manage a significant number of students and their information. | ||
| * Prefers desktop app over other types of apps. | ||
| * Can type fast. | ||
| * Prefers typing to mouse interactions. | ||
| * Reasonably comfortable using CLI apps. | ||
|
|
||
| ### Value proposition | ||
|
|
||
| * Manage student information faster than a typical mouse/GUI driven app. | ||
|
|
||
| ## User Stories | ||
|
|
||
| |Version| As a ... | I want to ... | So that I can ...| | ||
| |--------|----------|---------------|------------------| | ||
| |v1.0|Teaching Assistant|Add module|Keep track of all the modules that I am teaching| | ||
| |v1.0|Teaching Assistant|Add student|Keep track of students taking the module| | ||
| |v1.0|Teaching Assistant|Add assessment|Monitor what assessments there are in the module| | ||
| |v1.0|Teaching Assistant|Set marks|Record how much marks students score for the assessment| | ||
| |v1.0|Teaching Assistant|Set attendance|Monitor the attendance of students| | ||
| |v1.0|Teaching Assistant|Calculate the average marks of an assessment|Estimate the capabilities of students| | ||
| |v2.0|Teaching Assistant|Edit module|Change module details (e.g. code and name)| | ||
| |v2.0|Teaching Assistant|Delete module|Remove unnecessary data and reduce clutter| | ||
| |v2.0|Teaching Assistant|Edit student|Change any student's information| | ||
| |v2.0|Teaching Assistant|Delete student|Remove students who are no longer part of the class| | ||
| |v2.0|Teaching Assistant|Edit assessment|Change the name or weightage of the assessment| | ||
| |v2.0|Teaching Assistant|Delete assessment|Remove a particular assessment from the module| | ||
| |v2.0|Teaching Assistant|Edit marks|Modify the marks of the student for a particular assessment| | ||
| |v2.0|Teaching Assistant|Delete marks|Remove the marks entry of a student for a particular assessment| | ||
| |v2.0|Teaching Assistant|Delete attendance|Remove the attendance entry of a student| | ||
|
|
||
| ## Non-Functional Requirements | ||
| 1. Should work on any mainstream OS as long as it has `Java 11` installed. | ||
| 2. A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should | ||
| be able to accomplish most of the tasks faster using commands than using the mouse. | ||
|
|
||
| ## Glossary | ||
|
Comment on lines
-36
to
-38
There was a problem hiding this comment. I'm not sure if you're going you add this later but, perhaps adding some simple manual testing directions can guide the person to test functions you've described so far. |
||
| * Mainstream OS: Windows, Linux, Unix, OS-X | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
great work!