Software Development Report Requirements
When submitting a design of a program, a software design report is required. When submitting a completed program, a software development report is required. These documents should be written in a professional manner and are a technical document and should reflect that. A sample software development report is attached to this page.
Requirements for each type of report
When reporting on the design and/or development of software, the following items should be included:
|Software Design Report||Software Development report|
|Estimation of time required||✔|
|Analysis of time used||✔|
|Identification of outside resources used||✔||✔|
|Potential security risks||✔|
|Potential ethical implications||✔|
- If a given category is not appropriate in a given instance, still list the category and include "not applicable".
- Proper grammar and quality layout are required.
- Things need to be phased in the words of the developer (not directly quoted from the assignment).
Details for each category
Details about each category can be found below.
- Problem summary: This is a brief (one or two sentence) description of the problem being addressed. It is written in the problem domain language (not programming). It does not include implementation requirements. For example: if the problem was to write a tic-tac-toe game, this might be a single sentence such as “Develop a program to allow for a two-player tic-tac-toe game.”
- Implementation requirements: These are the specifics about what this implementation of a solution to the problem must include. There is where specific data types might be indicated. Or user interface requirements might be listed here. Bullet lists are a good format for this. For the tic-tac-toe example, it might include:
- Graphics are not necessary
- The system needs to allow the user to specify a filename containing a partially completed game to be loaded.
- The system needs to allow both players’ names to be entered
- The software needs to allow the game to be played by users on two different computers.
- System design: The level of this will depend on the complexity of the software and if object-oriented programming is being used.
- For primarily procedural code:
- A list of all methods/functions written (with arguments)
- Pseudo code of the non-trivial tasks of each method/function and/or main code
- For object-oriented code:
- A UML diagram containing all classes. Each class should include all field variables and methods properly documented
- For any non-trivial methods, pseudo code should be included in the system design.
- For primarily procedural code:
- Testing plan: A testing plan can include the following components
- Sufficient test cases
- tests of individual components of the software
- simple cases
- a number of larger test cases
- boundary test cases
- bad data test cases
- Each test cases should include:
- A title
- A short description
- Input used (specific values not a description). If the values are long enough, a reference to the file is sufficient if the file is included when submitting the work
- Expected output (specific values not a description).
- This is often formatted as a table.
- Sufficient test cases
- Testing report: This includes everything in the testing plan along with the achieved results and an indicator if the test was passed for each test case. If the software it is not at a stage where it can be tested, that should be explained here (in addition to the testing plan that would be used if the software could have been tested). This is typically the previous table with two additional columns
- Estimation of time required: This is a good faith estimate as to how long it will take to write the software. This can often be a single sentence.
- Analysis of time used: This is a statement of how long it took to write the software. Dividing that amount into the times spent designing, coding different components, testing, etc. is a good thing to do esp. as the software get more complex. This should also include a comparison to the estimation is one was previously made. This is normally a vary short paragraph.
- Identification of outside resources used: This is required. If no outside resources were used, the it should state that no outside resources were used. Use of the textbook or lecture notes need not be documented. The same with using provided code. However, in the code itself, any outside code (including provided code) needs to have a comment indicating where it came from.
- Potential security risks: This is a short bulleted list of potential security issues if there are any. Otherwise, indicate that none have been identified.
- Security report: This is a bulleted list of all known possible security issues associated with the software and how they were address, if they were addressed. Any unaddressed issues should be identified with a short statement as to the risk involved.
- Potential ethical implications: This is a short bulleted list of potential security issues if there are any. Otherwise, indicate that none have been identified.
- Ethical report: This is a bulleted list of all possible ethical issues associated with the software.
- Future improvements: This is a bulleted list of things could be improved in the software. This is not optional. There is always room for improvement. This can include what you would have liked to accomplish if you had the time. For the tic-tac-toe example it could include add graphics.
- Lessons learned. This is a bulleted list of at least two things you learned while writing the code.