Week 10 [Mon, Oct 19th] - Tutorial

1 before the tutorial Demonstrate an assertion failure

Task: Demonstrate an assertion failure using your tP code.
Objective: to verify that assertions are being checked when you run the code locally.

Here are the steps:

Java assertions are not enabled by default.
- If using Gradle to run your app, check if your build.gradle has been updated to enable assertions.
  If needed, update it as necessary.
- If using IntelliJ's native features to run your app (i.e., Gradle is not selected in this setting), check if you have enabled assertions in IntelliJ settings.
Modify the code of your tP to deliberately cause an assertion failure,
e.g., add assert false; somewhere in your code, in the path that is executed right after the app is launched.
Run the code so that the application crashes with an assertion failure. Note that the execution need to reach the assert statement you added above for the app to crash.
Take a screenshot that shows the assertion error message and save it somewhere. During the tutorial, the tutor will ask you to paste it in the tutorial workspace document.

2 before the tutorial Give examples of defensive programming

Note down examples of defensive programming from AB3 or your tP.
During the tutorial, the tutor will ask you for these examples.

3 before the tutorial Review sample extracts

Download the sample DG extracts in T10-DG-Extracts.pdf (in Canvas/Files/Handouts).
Evaluate the given extract to find errors or areas to improve. Note them down (e.g., add comments to the PDF file).
In particular, detect the following DG bugs (they are the same bugs against which your final DG will be evaluated).

Admin tP Grading → DG Bugs → Architecture Section → Possible Bugs

Architecture:

Symbols used are not intuitive
Indiscriminate use of double-headed arrows
diagrams contain lower-level details
Descriptions given are not sufficiently high-level

Admin tP Grading → DG Bugs → UML Diagrams → Possible Bugs

UML diagrams:

Notation incorrect or not compliant with the notation covered in the course.
Some other type of diagram is used when a UML diagram would have worked just as well.
The diagram used is not suitable for the purpose it serves.
The diagram is too complicated.

Admin tP Grading → General Documentation Bugs

Use of visuals

Not enough visuals e.g., screenshots/diagrams
The visuals are not well integrated into the explanation
The visuals are unnecessarily repetitive e.g., same visual repeated with minor changes

Use of examples:

Not enough or too many examples e.g., sample inputs/outputs

Explanations:

The target user for the product and/or the value proposition is not specified clearly.
The explanation is too brief or unnecessarily long.
The information is hard for the target audience to understand, e.g., because it uses terms the reader might not know

Neatness/correctness:

Looks messy
Not well-formatted
Broken links, other inaccuracies, typos, etc.
Hard to understand
Unnecessary repetitions (i.e., hard to see what's similar and what's different)

Usability:

Hard to navigate
Hard to read/see contents

Also, lookout for places where these tips can be applied.

Admin tP: Deliverables → DG → Tips

Aim to showcase your documentation skills. The primary objective of the DG is to explain the design/implementation to a future developer, but a secondary objective is to serve as evidence of your ability to document deeply technical content using prose, examples, diagrams, code snippets, etc., appropriately. To that end, you may also describe features that you plan to implement in the future, even beyond v1.6 (hypothetically).
For an example, see the description of the undo/redo feature implementation in the AddressBook-Level3 developer guide.
Use multiple UML diagram types. Following from the point above, try to include UML diagrams of multiple types to showcase your ability to use different UML diagrams.

FAQ Is it enough to update existing UML content/diagrams or must we add new content/diagrams?

FAQ What if the features I added don't affect UML diagrams?

FAQ What do we do when the UML notation covered in the course is not enough to model what we want to illustrate?

Diagramming tools:
- AB3 uses PlantUML (see the guide Using PlantUML @SE-EDU/guides for more info).

FAQ Instead of PlantUML, can I use some other tool?

FAQ Can UML diagrams be used in project submissions?

Keep diagrams simple. The aim is to make diagrams comprehensible, not necessarily comprehensive.
Ways to simplify diagrams:
- Omit less important details. Examples:
  - a class diagram can omit minor utility classes, private/unimportant members; some less-important associations can be shown as attributes instead.
  - a sequence diagram can omit less important interactions, self-calls, method parameters, etc.
    You can use ... (e.g., foo(...)) to indicate parameters have been omitted.
    You can use pseudocode instead of exact method calls e.g., save data in file instead of saveData(content, filename).
    Omit intricate details that complicate the diagram unnecessarily while adding little value to it e.g., exception handling (throw/catch), lambdas, calls to anonymous methods, etc.
    If you feel they are important to the purpose of the diagram (i.e., omitting them can mislead the reader), you can use a UML note to mention that information (as plain text) in the diagram.
- Omit repetitive details e.g., a class diagram can show only a few representative ones in place of many similar classes (note how the AB3 Logic class diagram shows concrete *Command classes using a placeholder XYZCommand).
- Limit the scope of a diagram. Decide the purpose of the diagram (i.e., what does it help to explain?) and omit details not related to it. In particular, avoid showing lower-level details of multiple components in the same diagram unless strictly necessary e.g., note how this sequence diagram shows only the detailed interactions within the Logic component i.e., does not show detailed interactions within the Model component.
- Break diagrams into smaller fragments when possible.
  - If a component has a lot of classes, consider further dividing into subcomponents (e.g., a Parser subcomponent inside the Logic component). After that, subcomponents can be shown as black-boxes in the main diagram and their details can be shown as separate diagrams.
  - You can use ref frames to break sequence diagrams into multiple diagrams. Similarly, rakes can be used to divide activity diagrams.
- Stay at higher levels of abstraction e.g., note how this sequence diagram shows only the interactions between architectural components, abstracting away the interactions that happen inside each component.
- Use visual representations as much as possible. E.g., show associations and navigabilities using lines and arrows connecting classes, rather than adding a variable in one of the classes.
- For some more examples of what NOT to do, see here.
Integrate diagrams into the description. Place the diagram close to where it is being described.
Use code snippets sparingly. The more you use code snippets in the DG, and the longer the code snippet, the higher the risk of it getting outdated quickly. Instead, use code snippets only when necessary and cite only the strictly relevant parts. You can also use pseudocode instead of actual programming code.
Resize diagrams so that the text size in the diagram matches the text size of the main text of the document. See example.

During the tutorial, the tutor will ask you for the observations you've noted down.