This site is from a past semester! The current version will be here when the new semester starts.
TIC4002 2021 Jan-May
**Schedule**
  • Full Timeline
  • Week 1 [Mon, Jan 11th]
  • Week 2 [Fri, Jan 15th]
  • Week 3 [Fri, Jan 22nd]
  • Week 4 [Fri, Jan 29th]
  • Week 5 [Fri, Feb 5th]
  • Week 6 [Fri, Feb 12th]
  • Week 7 [Fri, Feb 19th]
  • Week 8 [Fri, Mar 5th]
  • Week 9 [Fri, Mar 12th]
  • Week 10 [Fri, Mar 19th]
  • Week 11 [Fri, Mar 26th]
  • Week 12 [Fri, Apr 2nd]
  • Week 13 [Fri, Apr 9th]
  • Textbook
  • Admin Info
  • Dashboards
    • **Project Links**
     Individual Project (iP):
  • Individual Project Info
  • iP Upstream Repo
  • iP Showcase
  • iP Code Dashboard
  • iP Progress Dashboard
    •  Team Project (tP):
  • Team Project Info
  • tP Upstream Repo (AB3)
  • Team List
  • tP Code Dashboard
  • tP Progress Dashboard
    •
    **Other Links**
  • Report Bugs
  • Forum
  • Instructors
  • Announcements
  • Files (handouts, submissions etc.)
  • MS Teams link
  • Java Coding Standard
  • Git Conventions
  • Participation Dashboard
    •

    • Week 5 [Fri, Feb 5th] - Admin Info

    1. Submit post-lecture quiz counted for participation
    2. Practice peer evaluation on TEAMMATES Thu, Feb 11th 2359 counted for participation

    1 Submit post-lecture quiz counted for participation

    • Post-lecture quiz: Read weekly topics allocated for this week and submit the post-lecture quiz before the following lecture.

    2 Practice peer evaluation on TEAMMATES Thu, Feb 11th 2359 counted for participation

    • You should receive the submission link by Monday noon. Email tic4002@comp.nus.edu.sg if you did not receive the submission link on time.

    This module leverages peer feedback/evaluations in many ways. In particular, we do several rounds of peer evaluations using TEAMMATES.

    Tool: TEAMMATES (for Peer Evaluations)

    We use the TEAMMATES online peer evaluation system. TEAMMATES is a project run by NUS SoC students and used by over 0.5 million users from over 1000 universities.

    Preparation: When the first feedback session is open on TEAMMATES, you will receive an eamil from TEAMMATES. There is nothing for you to do until then.

    When you do receive that email, it will contain a unique link that you can use to access TEAMMATES without logging in first. Logging in to TEAMMATES using a Google account is optional (but doing so will allow you to see all your TEAMMATES sessions in one page).

    Submitting peer evaluations is compulsory. If you routinely miss submitting peer evaluations, you can lose participation marks.

    Session: Practice Peer Evaluation

    • Objective: to give you a chance to familiarize with the TEAMMATES tool
    • Held early in the semester
    • Submission is compulsory. However, your responses will not considered for grading as this session is for practice only.

    Policy on deadline extensions : OPTIONAL

    Learning to honor deadlines is a learning outcome of this module. Therefore, we do not normally extend module deadlines to accommodate those who missed the deadline, unless there are some extraordinary circumstances.

    + Other info relevant to this week:

    Admin tP: Grading

    Note that project grading is not competitive (not bell curved). Given below is the marking scheme.

    Total: 75 marks ( 65 individual marks + 10 team marks)

    See the sections below for details of how we assess each aspect.

    1. Project Grading: Product Design [ 5 marks]

    Evaluates:

    • how well your features fit together to form a cohesive product
      (not how many features or how big/novel/interesting/difficult the features are)
    • how well it matches the target user

    Evaluated by:

    • the teaching team (based on product demo and user guide)
    • peers from other teams (based on peer testing and user guide)

    Q Quality of the product design,
    Evaluate based on the User Guide and the actual product behavior.

    Criterion Unable to judge Low Medium High
    target user Not specified Clearly specified and narrowed down appropriately
    value proposition Not specified The value to target user is low. App is not worth using Some small group of target users might find the app worth using Most of the target users are likely to find the app worth using
    optimized for target user Not enough focus for CLI users Mostly CLI-based, but cumbersome to use most of the time Feels like a fast typist can be more productive with the app, compared to an equivalent GUI app without a CLI
    feature-fit Many of the features don't fit with others Most features fit together but a few may be possible misfits All features fit together to for a cohesive whole

    In addition, feature flaws reported in the PE will be considered when grading this aspect.

    Note that 'product design' or 'functionality' are not critical learning outcomes of the tP. Therefore, the bar you need to reach to get full marks will be quite low. For example, the Medium level in the rubric given in the panel above should be enough to achieve full marks. Similarly, only cases of excessive 'feature flaw' bugs will affect the score.

    These are considered feature flaws:
    The feature does not solve the stated problem of the intended user i.e., the feature is 'incomplete'
    Hard-to-test features
    Features that don't fit well with the product
    Features that are not optimized enough for fast-typists or target users

    2. Project Grading: Implementation [ 25 marks]

    2A. Code quality

    Evaluates: the quality of the parts of the code you claim as written by you

    Evaluation method: manual inspection by tutors + automated-analysis by a script

    Criteria:

    • At least some evidence of these (see here for more info)

      • logging
      • exceptions
      • assertions
      • defensive coding

    • No coding standard violations e.g. all boolean variables/methods sounds like booleans. Checkstyle can prevent only some coding standard violations; others need to be checked manually.

    • SLAP is applied at a reasonable level. Long methods or deeply-nested code are symptoms of low-SLAP.

    • No noticeable code duplications i.e. if there multiple blocks of code that vary only in minor ways, try to extract out similarities into one place, especially in test code.

    • Evidence of applying code quality guidelines covered in the module.

    2B. Effort

    Evaluates: how much value you contributed to the product

    Method:

    • Step 1: Evaluate the effort for the entire project. This is evaluated by peers who tested your product, and tutors.

    Q If the implementation effort required to create AB3 from scratch is 10, the estimated implementation effort of this team is, [0..20] e.g., if you give 8, that means the team's effort is about 80% of that spent on creating AB3. We expect most typical teams to score near to 10.

    • Do read the DG appendix named Effort, if any.
    • Consider implementation work only (i.e., exclude testing, documentation, project management etc.)
    • Do not give a high value just to be nice. Your responses will be used to evaluate your effort estimation skills.

    • Step 2: Evaluate how much of that effort can be attributed to you. This is evaluated by team members, and tutors.

    Q The team members' contribution to the product implementation (excluding UG, DG, and team-based tasks) is,

    • Baseline: If your team received a value higher than 10 in step 1 and the team agrees that you did roughly an equal share of implementation work, you should receive full marks for effort.

    3. Project Grading: QA [ 15 marks]

    3A. Developer Testing:

    Evaluates: How well you tested your own feature

    Based on:

    1. functionality bugs in your work found by others during the Practical Exam (PE)
    2. your test code (note our expectations for automated testing)
     
    • Expectation Write some automated tests so that we can evaluate your ability to write tests.

    🤔 How much testings is enough? We expect you to decide. You learned different types of testing and what they try to achieve. Based on that, you should decide how much of each type is required. Similarly, you can decide to what extent you want to automate tests, depending on the benefits and the effort required.
    There is no requirement for a minimum coverage level. Note that in a production environment you are often required to have at least 90% of the code covered by tests. In this project, it can be less. The weaker your tests are, the higher the risk of bugs, which will cost marks if not fixed before the final submission.

    These are considered functionality bugs:
    Behavior differs from the User Guide
    A legitimate user behavior is not handled e.g. incorrect commands, extra parameters
    Behavior is not specified and differs from normal expectations e.g. error message does not match the error

    3B. System/Acceptance Testing:

    Evaluates: How well you can system-test/acceptance-test a product

    Based on: bugs you found in the PE. In addition to functionality bugs, you get credit for reporting documentation bugs and feature flaws.

    Grading bugs found in the PE
    • Of Developer Testing component, based on the bugs found in your code3A and System/Acceptance Testing component, based on the bugs found in others' code3B above, the one you do better will be given a 70% weight and the other a 30% weight so that your total score is driven by your strengths rather than weaknesses.
    • Bugs rejected by the dev team, if the rejection is approved by the teaching team, will not affect marks of the tester or the developer.
    • The penalty/credit for a bug varies based on the severity of the bug: severity.High > severity.Medium > severity.Low > severity.VeryLow
    • The three types (i.e., type.FunctionalityBug, type.DocumentationBug, type.FeatureFlaw) are counted for three different grade components. The penalty/credit can vary based on the bug type. Given that you are not told which type has a bigger impact on the grade, always choose the most suitable type for a bug rather than try to choose a type that benefits your grade.
    • The penalty for a bug is divided equally among assignees.
    • Developers are not penalized for duplicate bug reports they received but the testers earn credit for duplicate bug reports they submitted as long as the duplicates are not submitted by the same tester.
    • i.e., the same bug reported by many testersObvious bugs earn less credit for the tester and slightly higher penalty for the developer.
    • If the team you tested has a low bug count i.e., total bugs found by all testers is low, we will fall back on other means (e.g., performance in PE dry run) to calculate your marks for system/acceptance testing.
    • Your marks for developer testing depends on the bug density rather than total bug count. Here's an example:
      • n bugs found in your feature; it is a big feature consisting of lot of code → 4/5 marks
      • n bugs found in your feature; it is a small feature with a small amount of code → 1/5 marks
    • You don't need to find all bugs in the product to get full marks. For example, finding half of the bugs of that product or 4 bugs, whichever the lower, could earn you full marks.
    • Excessive incorrect downgrading/rejecting/marking as duplicatesduplicate-flagging, if deemed an attempt to game the system, will be penalized.

    4. Project Grading: Documentation [ 15 marks]

    Evaluates: your contribution to project documents

    Method: Evaluated in two steps.

    • Step 1: Evaluate the whole UG and DG. This is evaluated by peers who tested your product, and tutors.

    Q Compared to AddressBoook-Level3 (AB3), the overall quality of the UG you evaluated is,
    Evaluate based on fit-for-purpose, from the perspective of a target user. For reference, the AB3 UG is here.

    Q Compared to AB3, the overall quality of the DG you evaluated is,
    Evaluate based on fit-for-purpose from the perspective of a new team member trying to understand the product's internal design by reading the DG. For reference, the AB3 DG is here.

    • Step 2: Evaluate how much of that effort can be attributed to you. This is evaluated by team members, and tutors.

    Q The team members' contribution to the User Guide is,

    Q The team members' contribution to the Developer Guide is,

    • In addition, UG and DG bugs you received in the PE will be considered for grading this component.

    These are considered UG bugs (if they hinder the reader):

    Use of visuals

    • Not enough visuals e.g., screenshots/diagrams
    • The visuals are not well integrated to 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 explanation is too brief or unnecessarily long.
    • The information is hard to understand for the target audience. e.g., using terms the reader might not know

    Neatness/correctness:

    • looks messy
    • not well-formatted
    • broken links, other inaccuracies, typos, etc.
    • hard to read/understand
    • unnecessary repetitions (i.e., hard to see what's similar and what's different)

    These are considered DG bugs (if they hinder the reader):

    These are considered UG bugs (if they hinder the reader):

    Use of visuals

    • Not enough visuals e.g., screenshots/diagrams
    • The visuals are not well integrated to 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 explanation is too brief or unnecessarily long.
    • The information is hard to understand for the target audience. e.g., using terms the reader might not know

    Neatness/correctness:

    • looks messy
    • not well-formatted
    • broken links, other inaccuracies, typos, etc.
    • hard to read/understand
    • unnecessary repetitions (i.e., hard to see what's similar and what's different)

    Architecture:

    • Symbols used are not intuitive
    • Indiscriminate use of double-headed arrows
    • e.g., the sequence diagram showing interactions between main componentsarchitecture-level diagrams contain lower-level details
    • Description given are not sufficiently high-level

    UML diagrams:

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

    Code snippets:

    • Excessive use of code e.g., a large chunk of code is cited when a smaller extract would have sufficed.

    Problems in User Stories. Examples:

    • Incorrect format
    • All three parts are not present
    • The three parts do not match with each other
    • Important user stories missing

    Problems in Use Cases. Examples:

    • Formatting/notational errors
    • Incorrect step numbering
    • Unnecessary UI details mentioned
    • Missing/unnecessary steps
    • Missing extensions

    Problems in NFRs. Examples:

    • Not really a Non-Functional Requirement
    • Not scoped clearly (i.e., hard to decide when it has been met)
    • Not reasonably achievable
    • Highly relevant NFRs missing

    Problems in Glossary. Examples:

    • Unnecessary terms included
    • Important terms missing

    5. Project Grading: Project Management [ 5 + 10 = 15 marks]

    5A. Process:

    Evaluates: How well you did in project management related aspects of the project, as an individual and as a team

    Based on: tutor/bot observations of project milestones and GitHub data

    Grading criteria:

    • Project done iteratively and incrementally (opposite: doing most of the work in one big burst)

    • Milestones reached on time (i.e., the midnight before of the lecture) (to get a good grade for this aspect, achieve at least 75% of the recommended milestone progress).

    • Good use of GitHub milestones mechanism.

    • Good use of GitHub releases mechanism.

    • Good version control, based on the repo.

    • Reasonable attempt to use the forking workflow at least for the early part of the project.

    • Good task definition, assignment and tracking, based on the issue tracker.

    • Good use of buffers (opposite: everything at the last minute).

    5B. Team-tasks:

    Evaluates: How much you contributed to team-tasks

    Here is a non-exhaustive list of team-tasks:

    1. Setting up the GitHub team org/repo
    2. Necessary general code enhancements e.g.,
      1. Work related to renaming the product
      2. Work related to changing the product icon
      3. Morphing the product into a different product
    3. Setting up tools e.g., GitHub, Gradle
    4. Maintaining the issue tracker
    5. Release management
    6. Updating user/developer docs that are not specific to a feature e.g. documenting the target user profile
    7. Incorporating more useful tools/libraries/frameworks into the product or the project workflow (e.g. automate more aspects of the project workflow using a GitHub plugin)

    Based on: peer evaluations, tutor observations

    Grading criteria: Do these to earn full marks.

    • Do close to an equal share of the team tasks (you can earn bonus marks by doing more than an equal share).
    • Have your code merged in at least five of weeks 6, 7, 8, 9, 10, 11, 12

    Admin Apdx B (Policies) → Policy on project work distribution

    Policy on project work distribution

    As most of the work is graded individually, it is OK to do less or more than equal share in your project team.

    Individual Expectations

    Individual Expectations on Implementation

    • Expectation Contribute to the functional code of the product.
      • User-visible features are preferred, but it is not a strict requirement.:
      • The enhancement(s) should fit with the rest of the software (and the target user profile) and should have the consent of the team members. You will lose marks if you go 'rogue' and add things that don't fit with the product.

    Some examples:

    • Add a new feature e.g. add the ability to view statistics
    • Enhance an existing features in a major way e.g. make the command syntax more user friendly and closer to natural language
    • A redesign of the GUI e.g. make it work like a chat application (note: chat is a form of CLI)
    • A redesign of the code e.g. Improve the design to improve the code quality.

    • Tip: Contribute to all aspects of the project e.g. write backend code, frontend code, test code, user documentation, and developer documentation. Reason: If you limit yourself to certain aspects only, you could lose marks allocated for the aspects you did not do. In addition, the final exam assumes that you are familiar with all aspects of the project.

    • Tip: Do all the work related to your enhancement yourself. Reason: If there is no clear division of who did which enhancement, it will be difficult to divide project credit (or assign responsibility for bugs detected by testers) later.
      In other words, we recommend that the work to be divided primarily based on features rather than components. The latter has the risk of a team member becoming a single point of failure and you becoming too reliant on other team members e.g., what if the person assigned to an important component doesn't deliver on time?.

    • Tip: Divide the components of the product among team members. Notwithstanding the above, you are still recommended to divide the components of the product among team members so that each team member is in charge of one or more components. While others will be modifying those components to fit their features, your role as the in charge of a component is to guide others modifying that component (reason: you are supposed to be the most knowledgeable about that component) and protect that component from degrading e.g., you can review others' changes to your component and suggest possible changes.

    Individual Expectations on Documentation

    • Objective: showcase your ability to write both user-facing documentation and developer-facing documentation.
    • Expectation Update the User Guide (UG) and the Developer Guide (DG) parts that are related to the enhancements you added. The minimum requirement is given below. (Reason: Evaluators will not be able to give you marks unless there is sufficient evidence of your documentation skills.)
      • UG: 1 or more pages
      • DG: 3 or more pages
    • Tip: If the UG/DG updates for your enhancements are not enough to reach the above requirements, you can make up the shortfall by documenting 'proposed' features and alternative designs/implementations.
    • Expectation Use at least 2 types of UML diagrams in your DG updates i.e., diagrams you added yourself or those you modified significantly.

    Individual Expectations on Testing

    • Expectation Write some automated tests so that we can evaluate your ability to write tests.

    🤔 How much testings is enough? We expect you to decide. You learned different types of testing and what they try to achieve. Based on that, you should decide how much of each type is required. Similarly, you can decide to what extent you want to automate tests, depending on the benefits and the effort required.
    There is no requirement for a minimum coverage level. Note that in a production environment you are often required to have at least 90% of the code covered by tests. In this project, it can be less. The weaker your tests are, the higher the risk of bugs, which will cost marks if not fixed before the final submission.

    Individual Expectations on Teamwork

    • Expectation Do an equal share of the team-tasks.

    Team-tasks are the tasks that someone in the team has to do.

    Here is a non-exhaustive list of team-tasks:

    1. Setting up the GitHub team org/repo
    2. Necessary general code enhancements e.g.,
      1. Work related to renaming the product
      2. Work related to changing the product icon
      3. Morphing the product into a different product
    3. Setting up tools e.g., GitHub, Gradle
    4. Maintaining the issue tracker
    5. Release management
    6. Updating user/developer docs that are not specific to a feature e.g. documenting the target user profile
    7. Incorporating more useful tools/libraries/frameworks into the product or the project workflow (e.g. automate more aspects of the project workflow using a GitHub plugin)

    • Expectation Carry an equal share of project roles and responsibilities.

    Roles indicate aspects you are in charge of and responsible for. E.g., if you are in charge of documentation, you are the person who should allocate which parts of the documentation is to be done by who, ensure the document is in right format, ensure consistency etc.

    This is a non-exhaustive list; you may define additional roles.

    • Team lead: Responsible for overall project coordination.
    • Documentation (short for ‘in charge of documentation’): Responsible for the quality of various project documents.
    • Testing: Ensures the testing of the project is done properly and on time.
    • Code quality: Looks after code quality, ensures adherence to coding standards, etc.
    • Deliverables and deadlines: Ensure project deliverables are done on time and in the right format.
    • Integration: In charge of versioning of the code, maintaining the code repository, integrating various parts of the software to create a whole.
    • Scheduling and tracking: In charge of defining, assigning, and tracking project tasks.
    • [Tool ABC] expert: e.g. Intellij expert, Git expert, etc. Helps other team member with matters related to the specific tool.
    • In charge of[Component XYZ]: e.g. In charge of Model, UI, Storage, etc. Note that being in charge of a component doesn't mean you are the only one who should be modifying that component. Rather, you are the one who's expected to, know that component best, review changes done to that component in v1.3-v1.4, act as the gate keeper of its quality, help others when they face difficulties while modifying that component etc.

    Ensure each of the important roles are assigned to one person in the team. It is OK to have a 'backup' for each role, but for each aspect there should be one person who is unequivocally the person responsible for it. Reason: when everyone is responsible for everything, no one is.

    • Expectation Review each others work. Reason: reviewing skills is a learning outcome, and it is mutually beneficial.