Code Check TM Software Requirements Specification

Transcription

1 Code Check TM Software Requirements Specification Author: Richard McKenna Debugging Enterprises TM Based on IEEE Std 830 TM (R2009) document format Copyright 2017 Debugging Enterprises No part of this publication may be reproduced in any form, in an electronic retrieval system or otherwise, without the prior written permission of the publisher. 1

2 1 Introduction Teaching Assistants in Computer Science courses typically must grade large numbers of student assignments each semester. The setup time for each assignment can be lengthy, depending on the technology used by a given course for managing student submissions. Stony Brook University uses Blackboard for providing student assignment grades, which also has a feature for students to submit their work. The problem with Blackboard is the process of retrieving student submissions and then extracting them into a format that works for grading is time consuming and involves a number of different steps and tools. Code Check will be a desktop application that will make it easier for Teaching Assistants to extract student submissions into a proper format to setup grading as well as setting up checks for code plagiarism (what we ll call a code check). 1.1 Purpose The purpose of this document is to specify how our Code Check program should look and operate. The intended audience for this document is all the members of the development team, from the instructors to the software engineers and designers. This document serves as an agreement among all parties and as a reference for how the code extraction tool should ultimately be constructed. Upon completing the reading of this document, one should clearly visualize how the application will look and operate as well as understand the way a generated site is setup. 1.2 Scope For this project the goal is for Teaching Assistants to have an easier time extracting student assignments for the purposes of grading and plagiarism checking. The assumption is that all submissions were made via Blackboard, which has its own submission formats. This will serve as our starting point. So, the application will not be about downloading submissions, that must be done via Blackboard using a Web browser. This application will take a collection of student submissions zipped up into a single file downloaded from Blackboard and will then extract these submissions and organize them into directories of unzipped work, ready to grade. In addition, Teaching Assistants will be given the opportunity to extract and organize the submitted source code to help with code plagiarism checks. Definitions, acronyms, and abbreviations Framework In an object-oriented language, a collection of classes and interfaces that collectively provide a service for building applications or additional frameworks all with a common need. GUI Graphical User Interface, visual controls like buttons inside a window in a software application that collectively allow the user to operate the program. 2

3 IEEE Institute of Electrical and Electronics Engineers, the world s largest professional association for the advancement of technology. UML Unified Modeling Language, a standard set of document formats for designing software graphically. Use Case Diagram A UML document format that specifies how a user will interact with a system. References IEEE Std 830 TM (R2009) IEEE Recommended Practice for Software Requirements Specification Overview This SRS will clearly define how the Code Check application should look and operate. Note that this is not a software design description (SDD), which would design how to construct the software using UML. This document does not specify how to build the appropriate technologies; it is simply an agreement concerning what to build. Section 2 of this document will provide the context for the project and specify all the conceptual design. Section 3 will present how the user interface should be laid out. Section 4 provides a Table of Contents, an Index, and References. 3

4 Overall description Here you are a Teaching Assistant in a Computer Science course like CSE 219 (Computer Science III), where you may be obligated to grade HW 1 submissions for 65 students. The current process for doing so would involve the following steps: 1. Open a Web browser like Chrome 2. Login to Blackboard 3. Navigate to the course page 4. Go to the Grade Center. Here one will find a table with student submissions waiting to be graded denoted by a be graded.. So, for example, Figure 2.1 shows a class roster with HW 1 yet to Figure 2.1 TA Grade Center view 5. For the assignment to be graded, click on the column and select the Assignment File Download option. This will bring one to the view shown in Figure 2.2 where one can select the student submissions to grade. 4

5 Figure 2.2 Student Assignment Selection for Download View 6. Click the check box next to the student names to be graded and press the Submit button. Upon doing this Blackboard will combine all selected student submissions into a single ZIP file and present a link to the user such that they may download this file. An example is shown in Figure 2.3 of such a link. Figure 2.3 Blackboard Download View 7. Right click on the link, this will open up a popup menu of choices. 8. Select Save Link As, which should open a dialog for saving the file. 9. Navigate to the directory where you wish to place it. 10. Name the ZIP file as you like and click the Save button. Now, via these 10 steps the TA can select and download student HW submissions. As shown the TA can select which assignment and which students. The result would be a single ZIP file that has all student ZIP files contained inside. We will not change this process in our application. The goal of our application is to make the remaining steps easier. 5

6 Current Extraction Process In order to make the grading process as smooth as possible students are encouraged to zip up and include their entire project regardless of IDE. So, if one is working in NetBeans, a student would select the project s parent directory for compression into a single ZIP file. It s also useful for students to submit multiple projects such that needed frameworks don t have to be linked but instead are included as part of the submission. This helps TAs as well. Currently, selected student assignments from our previous process are zipped up by Blackboard into a single file named and located according to the user s request. What happens to this file is where our program will come in. Currently, the Teaching Assistants would perform the following tasks. 1. Open a File Explorer type application 2. Navigate to the directory where the submissions were saved. For example, a TA may save the Blackboard-generated ZIP file as HW1.zip and save it into a directory called CSE219Summer2017HW1/blackboard/. 3. Right click on the file named HW1.zip. This should open a list of choices in a popup menu including something like Extract to HW1 directory. 4. Select the Extract to HW1 directory choice. This will unzip the single submission file into that directory, which will include all the student submissions and a text file for each student. Note that the student submission files will have long, hard to read and deal with names that will include the student homework number, the student Net ID, and a timestamp. This is one thing that s not so convenient for us. Super long paths like this can present problems so some graders who prefer to abbreviate these files to just the NetID. Note that students can submit all sorts of files, including PDFs or DOCs, like for writing assignments. We ll want to handle those cases as well, meaning cases where the submission is NOT a Zip file. But we ll have to be careful regarding how to deal with assignments where students are required to submit IDE projects, which must be as a single ZIP. One thing to note is that our project will be developed for the Java platform, which provides an easy to use library for dealing with ZIP files, but not RAR files. So students must be discouraged from submitting RAR files, and such submissions will be regarded as invalid as our program won t be able to extract data from them. 5. Navigate to the HW1 directory that was just unzipped. 6. Right-click on the student submission to extract. A popup menu should open up with an option to Extract to X directory, where X would be the name of the zip file. 7. Select Extract to X directory, which should unzip the student submission. Note that a TA has to do this separately for each student. This is very time consuming. Imagine a TA grading 100 students having to do this 100 times. 6

7 2.1 Product perspective Note that this process is just for grading. It doesn t even address plagiarism checks. Our program will aim to make all of these extraction and code organization steps much more convenient for the Teaching Assistant such that they can get on with the grading process more quickly System Interfaces The Code Check application will be a workspace-type application in the fact that we can create new code checks, save work regarding what s been extracted, and load an extraction that s already been saved. Understand, however, that the program uses a series of linked screens and corresponding operations that will allow the user to transition student work from a single ZIP file saved from Blackboard into work that can be graded or checked for plagiarism. Step 1: Select HW1.zip file -input: ZIP files of student ZIP files downloaded from Blackboard -input directory: work/assignment/blackboard -function: Extract -output: contents of downloaded ZIP files (student ZIP files) -output directory: work/assignment/submissions Step 2: Rename Student submission files -input: student submission ZIP files -input directory: work/assignment/submissions -function: Rename -output: renamed student submission files (ZIP files) -output directory: work/assignment/submissions Step 3: Unzip Student submission files -input: student submission ZIP files -input directory: work/assignment/submissions -function: Unzip -output: unzipped contents, one for each student -output directory: work/assignment/projects/netid (one directory for each student) Step 4: Extract Student Source Code -input: student project directories of files -input directory: work/assignment/projects/netid -function: Extract Source Code -output: directories of source code only -output directory: work/assignment/code/netid (one directory for each student) 7

8 Step 5: Code Check -input: directories of source code -input directory: work/assignment/code/netid -function: Perform Code Check -output: URL that contains a visual description of the Code Check results User Interfaces Our program will be a desktop application and so will make use of a mouse and keyboard for user input. Figure 2.4 below summarizes the ways with which the user will interact with our Code Check application, which will be further detailed using UML Use Case diagrams. These Use-Case diagrams should be fed as input directly into Section 3.1, external interfaces, which is where the design of the user interface is specified. Here is the full list of UML Use-Case Diagrams: Use Case UI Context Use Case 2.1 Welcome Dialog Create New Code Check 2.2 Welcome Dialog Select Recent Code Check to Load 2.3 Welcome Dialog Close Welcome Dialog 2.4 File Toolbar Create New Code Check 2.5 File Toolbar Load Code Check 2.6 File Toolbar Rename Code Check 2.7 File Toolbar Learn About Code Check 2.8 File Toolbar Exit Code Check 2.9 Edit Toolbar Navigate Home Step 2.10 Edit Toolbar Navigate to Previous Step 2.11 Edit Toolbar Navigate to Next Step 2.12 Extract Submissions Pane Extract Submissions 2.13 Rename Student Submissions Pane Rename Student Submissions 2.14 Unzip Student Submissions Pane Unzip Student Submissions 2.15 Extract Source Pane Toggle Source File Type 2.16 Extract Source Pane Add Custom File Type 2.17 Extract Source Pane Extract Source Code 2.18 Code Check Pane Run Code Check 2.19 Code Check Pane View Code Check Results 2.20 Multiple Panes Remove Table Item 2.21 Multiple Panes Refresh Table 2.22 Multiple Panes View Table Item Figure 2.4: Overview of Use-Case Diagrams 8

9 Use Case 2.1: Create New Code Check Use-Case: Create New Code Check Goal in Context: The user wishes to make a new code check Preconditions: The application has been started and the user is viewing the Welcome Dialog 1. User is viewing the Code Check application s Welcome Dialog 2. User clicks on the Create New Code Check link/button. A text dialog prompts the user for the name of the code check to perform. 3. User enters a unique code check name. The app will then create a directory with that name to the application s work directory. Inside that directory, empty subdirectories named submissions, projects, and code are added. The welcome Dialog is closed and the Main UI is opened and data is initialized and the user interface is reset with default values for a new code check. Exceptions: Should the user enter a code check name that already exists the user should be notified via a warning dialog and prompted for a name again. Note that the name prompt dialog should also have a Cancel option. When available: First Benchmark Frequency of use: Can only at maximum be used once per session Use Case 2.2: Select Recent Code Check to Load Use-Case: Select Recent Code Check to Load Goal in Context: The user wishes to load a recently edited code check that has already been created Preconditions: The application has been started and the user is viewing the Welcome Dialog 1. User is viewing the Code Check application s Welcome Dialog 2. User clicks on one of the links to a recently edited code check. The Welcome Dialog is closed. The Main UI is opened and data is initialized and the user interface is setup with values loaded from the selected code check Exceptions: Should any error occur during the loading of an existing code check the user should be notified via a warning dialog When available: First Benchmark Frequency of use: Can only at maximum be used once per session Use Case 2.3: Close Welcome Dialog Use-Case: Close Welcome Dialog Goal in Context: The user wishes to close the Welcome Dialog in order to bring forth the Main UI Preconditions: The application has been started and the user is viewing the Welcome Dialog 1. User is viewing the Code Check application s Welcome Dialog 2. User clicks on the dialog s X in the window s title bar. Welcome Dialog is closed. Main UI is opened without the workspace being loaded Exceptions: This is only available at the start of using the application as once the Welcome Dialog is 9

10 closed it is never opened again When available: First Benchmark Frequency of use: Can only at maximum be used once per session Use Case 2.4: Create New Code Check Use-Case: Create New Code Check Goal in Context: The user wishes to make a new code check Preconditions: The application has been started and the Main UI has been loaded 1. User is viewing the Code Check application s Main UI 2. User clicks on the Create New Code Check button. A text dialog prompts the user for the name of the code check to perform. 3. User enters a unique code check name. The app will then create a directory with that name to the application s work directory. Inside that directory, empty subdirectories named blackboard, submissions, projects, and code are added. The Main UI workspace is then initialized using default values and the user is brought to the Step 1 screen. Exceptions: Should the user enter a code check name that already exists or one for which a directory cannot be named the user should be notified via a warning dialog and prompted for a name again. Note that the name prompt dialog should also have a Cancel option. When available: First Benchmark Use Case 2.5: Load Code Check Use-Case: Load Code Check Goal in Context: The user wishes to load an existing code check that has already been created Preconditions: The code check to load must already exist 1. User is viewing the Code Check application s Main UI 2. User clicks on the Load Code Check button. The user will then be prompted via a File Chooser dialog to select a Code Check file. 3. The user selects an existing Code Check file and presses the File Chooser dialog s Open button. The File Chooser dialog is closed. The file s data is initialized and the user interface is setup with values loaded from the selected code check Exceptions: Should any error occur during the loading of an existing code check the user should be notified via a warning dialog When available: First Benchmark 10

11 Use Case 2.6: Rename Code Check Use-Case: Rename Code Check Goal in Context: The user wants to rename the code check that s loaded Preconditions: The application is running and a code check is loaded 1. User is working on a code check in any step of progress 2. User clicks on Rename Code Check button. User will be prompted for a new name (or to cancel). 3. User enters a new name for the current code check. If the name is valid, the current code check will be renamed. This means the file itself is renamed, but also the necessary directory is renamed. The window title bar must also be updated Exceptions: If the user enters an invalid name (i.e. can t be used as a directory name or already taken), the user should be notified via a dialog. When available: First Benchmark Use Case 2.7: Learn About Code Check Use-Case: Learn About Code Check Goal in Context: The user wants information about the application Preconditions: The application is running and the Main UI is loaded. 1. The user clicks on the About button. A message dialog opens displaying the name, author, and year of the application s development. The user may then read the desired information. 2. The user clicks the OK button to close the dialog. When available: First Benchmark Use Case 2.8: Exit Code Check Use-Case: Exit Code Check Goal in Context: The user wishes to exit the application Preconditions: The application is running and the Main UI is loaded. 1. User clicks the close button (i.e. X ) in the window title bar. The user will be prompted to verify that they wish to close the application. 2. The user clicks Yes to verify that they wish to exit. The application is then closed. When available: First Benchmark 11

12 Use Case 2.9: Navigate to Home Step Use-Case: Navigate to Home Step Goal in Context: The user wishes to navigate back to the first step for the currently loaded code check Preconditions: The user is currently viewing a screen other than Step 1 1. User is viewing a step screen other than Step 1 2. User clicks on Home Step button. Application switches to Step 1 screen 3. User views Step 1 screen When available: First Benchmark Use Case 2.10: Navigate to Previous Step Use-Case: Navigate to Previous Step Goal in Context: User wishes to go to the previous step screen Preconditions: User is currently viewing a step screen other than Step 1 1. User is viewing a step screen other than Step 1 2. User clicks on Previous Button. This will change the current screen to the previous step screen. When available: First Benchmark Use Case 2.11: Navigate to Next Step Use-Case: Navigate to Next Step Goal in Context: User wishes to go to the next step screen Preconditions: User is currently viewing a step screen other than Step 1 1. User is viewing a step screen other than Step 1 2. User clicks on Next Button. This will change the current screen to the next step screen. When available: First Benchmark Use Case 2.12: Extract Submissions Use-Case: Extract Submissions Goal in Context: User wishes to extract all student ZIP files from the collections of ZIP files downloaded from Blackboard Preconditions: User is viewing Step 1 screen and the table has at least one item 12

13 1. User is viewing Step 1 screen 2. User selects at least one ZIP file in table 3. User clicks Extract button. This will unzip all contents of all selected Blackboard ZIP files to the current code check s submissions directory. When available: Second Benchmark Use Case 2.13: Rename Student Submissions Use-Case: Rename Student Submissions Goal in Context: Big long student submission ZIP file names are a pain to deal with. In this step the user may shorten them to NetID named files. Preconditions: User is editing an existing code check and the contents of the downloaded ZIP file from Blackboard have already been extracted. 1. User is viewing a list of student submission ZIP files. 2. User clicks Rename button. This will shorten all student submissions to just their NetID.zip When available: Second Benchmark Use Case 2.14: Unzip Student Submissions Use-Case: Unzip Student Submissions Goal in Context: User wishes to unzip student ZIP files Preconditions: Submitted student ZIP files have already been extracted from the ZIP file downloaded from Blackboard 1. User is viewing the Step 3 screen. 2. User selects the student submissions to extract 3. User clicks the Unzip button. This will create a directory for each student in the projects directory. When available: Second Benchmark Use Case 2.15: Toggle Source File Type Use-Case: Toggle Source File Type Goal in Context: User wishes to select the types of source file extensions on which to extract for plagiarism check Preconditions: User is viewing step 4 screen 13

14 1. User is viewing step 4 screen 2. User clicks on source file extension checkboxes to enable/disable When available: Second Benchmark Use Case 2.16: Add Custom File Type Use-Case: Add Custom File Type Goal in Context: User wishes to do a code check on a type of source code file not listed Preconditions: User is viewing the step 4 screen 1. User is viewing the Step 4 screen 2. User clicks inside custom file type check box. 3. User types desired file extension When available: Second Benchmark Use Case 2.17: Extract Source Code Use-Case: Extract Source Code Goal in Context: User wishes to extract only source code files from unzipped projects Preconditions: User is viewing the step 4 screen and there are submissions in the table 1. User is viewing the Step 4 screen and there are unzipped projects in the table 2. User clicks the Extract Code button. This will search all student projects and find the desired source files and copy them into their proper student directories When available: Second Benchmark Use Case 2.18: Run Code Check Use-Case: Run Code Check Goal in Context: User wishes to perform a code check on the loaded work Preconditions: User is viewing the step 5 screen and there are submissions in the table 1. User is viewing the Step 5 screen and there are extracted code submissions in the table 2. User clicks on the Code Check button. Code check feedback is printed into the text 14

15 area. When available: Second Benchmark Use Case 2.19: View Code Check Results Use-Case: View Code Check Results Goal in Context: User wishes to view the results of the code check Preconditions: User has already performed a Code Check for the work loaded 3. User is viewing the Step 5 screen and a code check has been completed 4. User clicks on the View Results button, which is only enabled if a code check has been completed for the current work. This opens a new dialog window that contains a simple Web browser that is viewing the results page 5. User clicks on results links as desired to navigate between code check results. 6. User clicks dialog X to close. When available: Second Benchmark. Use Case 2.20: Remove Table Item Use-Case: Remove Table Item Goal in Context: User wishes to remove a table item Preconditions: User is viewing one of the five Step screens and at least one item is in the table 1. User is viewing one of the Step screens. 2. User selects one of the items in the table (Blackboard submission file, submitted zip file, user directory, etc.) 3. User clicks on Remove button. This will open a dialog that will give the user an Ok/Cancel choice to verify the decision. 4. User clicks Ok to verify removing the item. Item will be removed from the item and deleted from the file system. Exceptions: User may click Cancel to avoid accidentally removing item. When available: Second Benchmark 15

16 Use Case 2.21: Refresh Table Use-Case: Refresh Table Goal in Context: User wishes to see the latest list of items Preconditions: User is viewing one of the five Step screens 1. User is viewing one of the five step screens 2. User presses the Refresh button. The table is then reloaded with the latest information. The reason this is necessary is that items can be deleted or even added externally via the file system When available: Second Benchmark Use Case 2.22: View Table Item Use-Case: View Table Item Goal in Context: User wishes to view the contents of a table item Preconditions: User is viewing one of the five Step screens and at least one item is in the table 1. User is viewing one of the Step screens. User selects an item from one of the tables 2. User selects one of the items in the table (Blackboard submission file, submitted zip file, user directory, etc.) 3. User clicks on View button. This will open a dialog with a view of the full contents of the file or directory Exceptions: This feature is only enabled for when the user selects a single file. If multiple files are selected the View button must be disabled and then reenabled when only one table item is selected. When available: Second Benchmark 16

17 i. Hardware Interfaces The application should be runnable on any platform that supports Java, but would require a keyboard and mouse. ii. Software Interfaces Code Check will be developed using the Java language. Note that since it is a traditional workspace-type application, it may be best to use the Desktop Java Framework. iii. Communications Interfaces Note that this editing application will operate locally but an Internet connection will be required to perform the Code Check plagiarism submission and to check results. iv. Memory Constraints The application is dependent upon student submissions. If those are gigantically large it could affect product performance. v. Operations Note that grading would be done using the IDE used for creating the ZIPped up project files. N/A vi. Site Adaptation Requirements N/A. b. Product functions c. User characteristics 17

18 The editor should aim to be as user friendly as possible, using the principles of foolproof design as well as sound UI design principles. N/A d. Constraints e. Assumptions and dependencies N/A f. Apportioning of the Requirements N/A 18

19 3 Specific requirements A Code Check has five steps, as indicated by the previously described five screens. Following are visual depictions of these screens. Note that all operations requiring file extraction and copying will employ progress bars to show the user how far along work has progressed. 3.1 External interfaces The following wireframe mockups provide a look at the types of controls and layout to be used for the User Interface. Note that the User Interface designer should select the appropriate icons for all buttons and should carefully choose color and font combinations that provide good contrast and attract the eye. Note that the User Interface designer should also consider additional dialogs for providing adequate feedback to the user as well as for navigation through the file system to select files and directories as part of certain use cases. Figure 3.1 Welcome Dialog 19

20 Figure 3.2 Extract Blackboard Submissions Figure 3.3 Rename Student Submissions 20

21 Figure 3.4 Unzip Student Submissions 21

22 Figure 3.5 Extract Source Code Figure 3.6 Code Check 22

23 3.2 Functions One of the important things to consider in our application is providing the appropriate feedback to the user. Users need feedback to enjoy their experience. This is typically done with visual cues like dialog boxes. 3.3 Performance requirements N/A 3.4 Logical database requirements N/A 3.5 Design constraints JavaFX will be used because it effectively leverages each system s available rendering technologies and provides platform independence for personal computers. 3.6 Software system attributes As professionals, all members of this project must take this project seriously. We are dedicated to producing robust software that exceeds the expectations of our customers. In order to achieve this level of quality, we should build a product with the following properties in mind: Reliability The program should be carefully planned, constructed and tested such that it behaves flawlessly for the end user. Bugs, including rendering problems, are unacceptable. In order to minimize these problems, all software will be carefully designed using UML diagrams and a Design to Test approach should be used for the Implementation Stage Availability Customers may download and install the application for free Security All security mechanisms will be addressed by future revisions Extensibility It is possible that more JavaScript/JSON widgets might be added to course sites in the future, so by providing an additional tab with suitable data and making changes to exporting methods, this should be considered during this deaign Portability To start with, the app will target desktop Java applications Maintainability Update mechanisms will be addressed by future revisions. 23

24 3.7 Organizing the specific requirements Note that the application is simple enough that we need not worry about using an alternative arrangement of the content of this document. The specific requirements for this application already fit neatly into the sections listed in the IEEE s recommended SRS format. 3.8 Additional comments It is important to keep in mind that the plagiarism check results will be provided via a URL. The work done by that program is proprietary and not performed by this application. 24

25 4 Supporting Information Note that this document should serve as a reference for the designers and coders in the future stages of the development process, so we ll provide a table of contents to help quickly find important sections. 4.1 Table of contents 1. Introduction 1. Purpose 2. Scope 3. Definitions, acronyms, and abbreviations 4. References 5. Overview 2. Overall description 1. Product perspective 2. Product functions 3. User characteristics 4. Constraints 5. Assumptions and dependencies 3. Specific requirements 1. External interfaces 2. Functions 3. Performance requirements 4. Logical database requirements 5. Design constraints 6. Software system attributes 7. Organizing the specific requirements 8. Additional comments 4. Supporting Information 1. Table of contents 2. Appendixes 4.2 Appendixes N/A 25