Week 10 [Mon, Oct 20th] - Project

tP:

  1. Start the next iteration
  2. Update the DG with design details IMPORTANT
  3. Ensure the code is RepoSense-compatible

tP: mid-v2.0

Intro to tP Week 10

Things to note:

  • Set moderate targets for functionality. Adding more functionality than needed will not earn you more marks but can expose you to higher risk of bugs.
    Focus on improving the process and the quality instead.
  • Move in small steps, and keep the product working at each step. If it breaks, you will only have to examine the latest change for the cause of the breakage.

1 Start the next iteration

As you did in the previous iteration,

  • Plan the next iteration (steps are given below as a reminder):
    • Decide which enhancements will be added to the product in this iteration, assuming this is the last iteration.
    • If possible, split that into two incremental versions v2.0 and v2.0b.
    • Divide the work among team members.
    • Reflect the above plan in the issue tracker.
  • Start implementing the features as per the plan made above.
  • Track the progress using GitHub issue tracker, milestones, labels, etc.

In addition,

  • Maintain the defensiveness of the code: Remember to use assertions, exceptions, and logging in your code, as well as other defensive programming measures when appropriate.
    Remember to enable assertions in your IDEA run configurations and in the gradle file.
  • Recommend: Each PR should also update the relevant parts of documentation and tests. That way, your documentation/testing work will not pile up towards the end.

2 Update the DG with design details IMPORTANT

Do this before next week Wednesday (Wed, Oct 29th ) so that the added sequence diagrams can get peer feedback via the DG peer review that will happen during this week's tutorial. Diagrams you add before the deadline will receive feedback while diagrams added later will not.

  • Update the Developer Guide as follows:
    • Each member should describe the implementation of at least one enhancement she has added (or planning to add).
      Expected length: 1+ page per person
    • Describing the design at a multiple-levels (e.g., first, describe at architecture-level, then describe at component-level) is optional. It is also acceptable to have one Design & Implementation section in which you describe the entire thing at the class- and object-level.
    • The description can contain things such as,
      • How the feature is implemented (or is going to be implemented).
      • Why it is implemented that way.
      • Alternatives considered.
    • Minimally, add sequence diagrams to enhance your DG wherever they can be useful.
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 v2.1 (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 What do we do when the UML notation covered in the course is not enough to model what we want to illustrate?

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 complicated the diagram unnecessarily they add to the diagram 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.
    • 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 to multiple diagrams.
    • 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 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 only. 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 diagram. See example.

3 Ensure the code is RepoSense-compatible

  • Ensure your code is and the code it attributes to you is indeed the code written by you, as explained below:

    • Go to the tp Code Dashboard. Click on the </> icon against your name and verify that the lines attributed to you (i.e., lines marked as green) reflects your code contribution correctly. This is important because some aspects of your project grade (e.g., code quality) will be graded based on those lines.
          

    • More info on how to make the code RepoSense compatible:

FAQ What if someone took over a feature from another team member?