This site is from a past semester! The current version will be here when the new semester starts.

Week 4 [Fri, Sep 1st] - Project

iP:

  1. Use GFMD in the PR description
  2. Review some peer PRs
  3. Learn from others (optional)
  4. Add Increments as branches: A-CheckStyle, Level-10, A-Varargs

tP:

  1. Start weekly project meetings
  2. Start a collaborative doc to take project notes before the tutorial
  3. Decide on an overall project direction (user profile, problem addressed) before the tutorial

iP

Mac users: Ensure you have followed the advisory given here.

1 Use GFMD in the PR description

  • GitHub Flavored Markdown (and Markdown in general) is useful in many places when using GitHub e.g., issue tracker, PR reviews, writing documentation. The aim of this task is to ensure that you are sufficiently familiar with the GFMD syntax.
  • Requirements: Update the description of the iP PR you created earlier (do not add a new comment) so that it contains the following GFMD elements:
    1. a heading
    2. a bullet list
    3. a numbered list
    4. a fenced code block (with syntax highlighting)
    5. a task list
    6. an emoji
    7. a blockquote
    8. a hyperlink
    9. inline code
    10. some text formatting: bold, italic, strikethrough etc.

Here is an example:

DukePro

“Your mind is for having ideas, not holding them.” – David Allen (source)

DukePro frees your mind of having to remember things you need to do. It's,

  • text-based
  • easy to learn
  • FAST SUPER FAST to use

All you need to do is,

  1. download it from here.
  2. double-click it.
  3. add your tasks.
  4. let it manage your tasks for you 😉

And it is FREE!

Features:

  • Managing tasks
  • Managing deadlines (coming soon)
  • Reminders (coming soon)

If you Java programmer, you can use it to practice Java too. Here's the main method:

public class Main {
    public static void main(String[] args) {
        Application.launch(MainApp.class, args);
    }
}

If you wish, you may write the PR description to be very similar to the example given above -- as the goal here is to demonstrate your mastery of the GFMD syntax (not ad writing skills).

2 Review some peer PRs

Please wait till Mon, Sep 4th to start this task, to give others a few extra days to create the PR if they haven't done so yet.

This task is worth 2x2=4 participation points.

  • Learn how you should review PRs in this task:
Video

  • Step 1 Note these additional guidelines:

    • Read the Best practices for reviewing PRs @SE-EDU/guides. You are expected to follow all of them.
    • Make sure you add 'review comments' (not regular comments) as only those are counted for participation. See step 4 in the panel above to find how to add 'review comments'.
    • If the PR has received some review comments already, feel free to confirm/complement/question those comments in your review. Also, look for things the previous reviewers may have missed.
    • At the end of the review, choose Comment (i.e., not Approve or Request changes)

  • Step 2 Do the first PR review as follows.

    • Give comment on coding standard related issues only.
      Review comments don't always have to be about problems in the code. Other things you can do:
      • complement the author on not making a common mistake
      • ask questions
      • suggest alternatives
    • The review allocation is given in the panel below.

If the student you have been allocated to review has not created a PR (or the PR has a trivial amount of code), you can review the Backup PR to review provided in the allocation table. Failing both, review another PR allocated to another student in your own tutorial but not in your team.

Tip for future reference: GitHub allows you to filter PRs/Issues using various criteria such as author:AuthorUsername (example -- see the filters text box in the target page).

Alternatively, you can use PR labels (if any) to filter PRs/Issues.

FAQ: How many comments should I add? Answer: Depends on the code being reviewed but we expect most PRs would warrant at least 4-5 comments. If the PR is huge, you can stop when you think you've put in a fair amount of time on the job (~15 minutes) and added enough comments for the PR author to receive some value.

  • Step 3 Do the second PR review as follows.
    • Comment on other code quality guidelines (see the section Naming in this textbook chapter) you have learned so far. It's optional to comment on coding standard violations in this PR review.
    • The review allocation is given in the panel below.

If the allocated PR is not suitable, use the same strategy as before to find an alternative PR to review.

  • Step 4 [When you receive reviews for your own PR] Respond to comments received. You are recommended to (but not obliged to) respond to comments received from peers, especially if the PR reviewer asked you for more info. As mentioned in these guidelines, do not get into arguments with PR reviewers/authors.

3 Learn from others (optional)

  • You can use the iP Code Dashboard to view others' iP code, using the Links → iP Code Dashboard item in the top navigation menu of this course website.We encourage you to read others’ code and learn from them. If you adopt solutions from others (also encouraged), please follow our reuse policy. 

Click on the  icon corresponding to a student name to see the code written by that person.

Similarly, click on the  icon to see a list of tags (and commits) -- this way, you can find which increments have been done by a particular student.

4 Add Increments as branches: A-CheckStyle, Level-10, A-Varargs

Duke A-CheckStyle: Use CheckStyle optional

Attention Mac users! If you are not using the exact JDK distribution specified by our advisory for Mac users in this page, you are likely to run into problems while doing Level-10.

Duke Level-10: GUI

Note that you no longer need to keep the text-based UI after adding a GUI. Similarly, there is no need to use the I/O redirection style automated testing anymore (that technique is suited for text UIs only).

Duke A-Varargs: Use Varargs if-applicable

tP: Set direction

1 Start weekly project meetings

  • We recommend you start weekly project meetings now. You can use the meeting to do tP tasks, but also help each other do iP tasks. On a related note, it is also acceptable to discuss weekly post-lecture quiz (if any) together with team members as you do the quiz i.e., discuss and decide the answer collectively, but you should not give away your answers to someone who was not part of that discussion.

2 Start a collaborative doc to take project notes before the tutorial

  • Keep project notes in easy-to-use collaborative docs (Recommended: use a GoogleDoc). This document will be checked by the instructors at various points.
    Remember to choose a tool that allow public view access e.g., GoogleDoc can be shared via a public link so that the document can be viewed by others. You'll be asked to submit this link to us in the next week.
    Make sure all you current and future project notes (if split into in multiple documents) are reachable via links given in this document and are viewable by the public.

3 Decide on an overall project direction (user profile, problem addressed) before the tutorial

  • Decide project direction, target user profile, and problem addressed: Use your first project meeting to discuss with your team members and decide your project direction, target user profile, and the value proposition of the product, as described in the panels below:

As we are still at the early stages of identifying a problem to solve, do not think of the product (i.e., the solution) yet. That is, do not discuss the product features, UI, command format, and implementation details, etc. unless they are pertinent to the decision of the project direction.

You can use the button in a panel to open it as a new tab (it can be expanded in-place too). This feature is available only for panels containing another full page of the website (i.e., not available if the panel contains an extract of a page).

Admin tP: Expectations

Admin tP: Constraints

Pick the morph option at your own risk: As mentioned elsewhere, morph option (i.e., aiming to build an application that manages anything other than contacts) is the harder option, especially at the start of tP coding (morphing is an extensive change that needs to be done very early in the project, and quickly). Choose it only if your team has at least one strong programmer who is willing to invest extra effort to create a 'different' application.

Pick a CLI-friendly product domain: Given Recommendation-CLI-First and Constraint-Typing-Preferred mentioned in the panels above, it makes sense to pick a product domain that is more suitable for CLI interactions i.e., a product that deals with easy-to-type textual data, needs a small number of data fields, and each data field is short. For example, a blog editor is an unsuitable product domain because it also deals with non-text data (e.g., images, videos) and some data fields are quite long (i.e., paragraphs of text). Similarly, keeping track of extensive employee records may be an unsuitable domain if there are many data fields per employee.

  • Submission: Submit via TEAMMATES.
    • Details to submit:
      1. Product name (plain text only) e.g., ClientContactsPro
      2. Target user profile (plain text only) e.g., freelance event photographers
      3. Value proposition i.e., what problem does the product solve? (plain text paragraph, no more than 50 words) e.g., provide fast access to client contact details, optimized for users who prefer a CLI
        This is not a list of features -- you should not think about exact features yet.
      4. Link to the project notes document: This should be an online document/page (not a folder) -- e.g., a GoogleDoc (not a Google Drive location) -- that is publicly accessible. If your project notes are in multiple locations/files, this one document should contain the link to the other documents with guidance on which link is for what.
    • You'll receive an email from TEAMMATES with the submission link. Only one member needs to submit on behalf of the team. All members can view/update the submission.
    • Submission link will be sent to you by Mon, Sep 4th (reason: we need a few days to set up the submission system after teams have been finalized).
    • FAQ: Can we change these values later?
      Answer: Yes. If the submission deadline is not over yet, use the same link to update the submission. If the submission deadline is over, email the updated name, target user, value proposition to cs2103@comp.nus.edu.sg.