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

Week 12 [Fri, Oct 30th] - Project

tP:

Update the DG with design details IMPORTANT
Draft the PPP
Double-check RepoSense compatibility

tP: mid-v3.0

1 Update the DG with design details IMPORTANT

Update the Developer Guide as follows:
- You can take some inspiration from the DG of the AB3 (se-edu/addressbook-level 3) project.
- 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.

Admin tP Deliverables → DG → Tips

Aim to showcase your documentation skills. The stated objective of the DG is to explain the 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 v3.0 (hypothetically).
For an example, see the description of the undo/redo feature implementation in the AddressBook-Level3 developer guide.
Diagramming tools:
- AB3 uses PlantUML (see the guide Using PlantUML @SE-EDU/guides for more info).
- You may use any other tool too (e.g., PowerPoint). But if you do, note the following:
  Choose a diagramming tool that has some 'source' format that can be version-controlled using git and updated incrementally (reason: because diagrams need to evolve with the code that is already being version controlled using git). For example, if you use PowerPoint to draw diagrams, also commit the source PowerPoint files so that they can be reused when updating diagrams later.
- Can i.e., automatically reverse engineered from the Java codeIDE-generated UML diagrams be used in project submissions? Not a good idea. Given are three reasons each of which can be reported by evaluators as 'bugs' in your diagrams, costing you marks:
  - They often don't follow the standard UML notation (e.g., they add extra icons).
  - They tend to include every little detail whereas we want to limit UML diagrams to important details only, to improve readability.
  - Diagrams reverse-engineered by an IDE might not represent the actual design as some design concepts cannot be deterministically identified from the code. e.g., differentiating between multiplicities 0..1 vs 1, composition vs aggregation
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.
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.
- 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 sub-components (e.g., a Parser sub-component inside the Logic component). After that, sub-components 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 pseudo code instead of actual programming code.
Resize diagrams so that the text size in the diagram matches the the text size of the main text of the diagram. See example.

2 Draft the PPP

Create the first version of your Project Portfolio Page (PPP).
Reason: Each member needs to create a PPP to describe your contribution to the project.

At the end of the project each student is required to submit a Project Portfolio Page.

PPP Objectives

For you to use (e.g. in your resume) as a well-documented data point of your SE experience
For evaluators to use as a data point for evaluating your project contributions

PPP Sections to include

Overview: A short overview of your product to provide some context to the reader. The opening 1-2 sentences may be reused by all team members. If your product overview extends beyond 1-2 sentences, the remainder should be written by yourself.
Summary of Contributions --Suggested items to include:
- Code contributed: Give a link to your code on tP Code Dashboard. The link is available in the Project List Page -- linked to the icon under your profile picture.
- Enhancements implemented: A summary of the enhancements you implemented.
- Contributions to documentation: Which sections did you contribute to the UG?
- Contributions to the DG: Which sections did you contribute to the DG? Which UML diagrams did you add/updated?
- Contributions to team-based tasks :
- Review/mentoring contributions: Links to PRs reviewed, instances of helping team members in other ways
- Contributions beyond the project team:
  - Evidence of helping others e.g. responses you posted in our forum, bugs you reported in other team's products,
  - Evidence of technical leadership e.g. sharing useful information in the forum

Keep in mind that evaluators will use the PPP to estimate your project effort. We recommend that you mention things that will earn you a fair score e.g., explain how deep the enhancement is, why it is complete, how hard it was to implement etc..

[Optional] Contributions to the Developer Guide (Extracts): Reproduce the parts in the Developer Guide that you wrote. Alternatively, you can show the various diagrams you contributed.
[Optional] Contributions to the User Guide (Extracts): Reproduce the parts in the User Guide that you wrote.

PPP Format

File name (i.e., in the repo): docs/team/githbub_username_in_lower_case.md e.g., docs/team/goodcoder123.md
Follow the example in the AddressBook-Level3

To convert the UG/DG/PPP into PDF format, go to the generated page in your project's github.io site and use this technique to save as a pdf file. Using other techniques can result in poor quality resolution (will be considered a bug) and unnecessarily large files.

Ensure hyperlinks in the pdf files work. Your UG/DG/PPP will be evaluated using PDF files during the PE. Broken/non-working hyperlinks in the PDF files will be considered as bugs and will count against your project score. Again, use the conversion technique given above to ensure links in the PDF files work.

The icon indicates team submissions. Only one person need to submit on behalf of the team but we recommend that others help verify the submission is in order i.e., the responsibility for (and any penalty for problems in) team submissions are best shared by the whole team rather than burden one person with it.

The icon indicates individual submissions.

PPP Page Limit

Content	Recommended	Hard Limit
Overview + Summary of contributions	0.5-1	2
[Optional] Contributions to the User Guide	0.5
[Optional] Contributions to the Developer Guide	1.5

The page limits given above are after converting to PDF format. The actual amount of content you require is actually less than what these numbers suggest because the HTML → PDF conversion adds a lot of spacing around content.

3 Double-check RepoSense compatibility

Once again, double-check to ensure the code attributed to you by RepoSense is correct.

Ensure your code is i.e., RepoSense can detect your code as yoursRepoSense-compatible 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:

Tool: RepoSense (for authorship tracking)

We will be using a tool called RepoSense to make it easier for you to see (and learn from) code written by others, and to help us see who wrote which part of the code.

_{Figure: RepoSense Report Features}

Viewing the current status of code authorship data:

The reports generated by the tool for the individual and team projects will be made available in the module website at some point in the semester. The feature that is most relevant to you is the Code Panel (shown on the right side of the screenshot above). It shows the code attributed to a given author.
Click on your name to load the code attributed to you (based on Git blame/log data) onto the code panel on the right.
If the code shown roughly matches the code you wrote, all is fine and there is nothing for you to do.

If the code does not match the actual authorship: Given below are the possible reasons for the code shown to mismatch the code you wrote.

Reason 1: the Author name of some of your commits is not known to RepoSense -- this is a result of not setting the git.username property as instructed in our Git setup instructions.
How to check: Find the Author name of your commits that are missing (you can use SourceTree or the git log command for that -- it's not possible to do that using the GitHub interface though).
Check if that author name is included in the RepoSense config for the iP or the RepoSense config for the tP (whichever the applicable one)
Remedy: Send the missing author name(s) to the prof so that the RepoSense configuration can be updated accordingly.
Reason 2: The actual authorship does not match the authorship determined by git blame/log e.g., another student touched your code after you wrote it, and Git log attributed the code to that student instead.
Remedy: You can add @@author annotations as explained in the panel below:

Adding `@@author` tags indicate authorship

Mark your code with a //@@author {yourGithubUsername}. Note the double @.
The //@@author tag should indicates the beginning of the code you wrote. The code up to the next //@@author tag or the end of the file (whichever comes first) will be considered as was written by that author. Here is a sample code file:
```
//@@author johndoe
method 1 ...
method 2 ...
//@@author sarahkhoo
method 3 ...
//@@author johndoe
method 4 ...
```
If you don't know who wrote the code segment below yours, you may put an empty //@@author (i.e. no GitHub username) to indicate the end of the code segment you wrote. The author of code below yours can add the GitHub username to the empty tag later. Here is a sample code with an empty author tag:
```
method 0 ...
//@@author johndoe
method 1 ...
method 2 ...
//@@author
method 3 ...
method 4 ...
```
The author tag syntax varies based on file type e.g. for java, css, fxml. Use the corresponding comment syntax for non-Java files.
Here is an example code from an xml/fxml file.
```

<textbox>
  <label>...</label>
  <input>...</input>
</textbox>
...
```

Do not put the //@@author inside java header comments.
👎

/**
  * Returns true if ...
  * @@author johndoe
  */

👍

//@@author johndoe
/**
  * Returns true if ...
  */

What to and what not to annotate

Annotate both functional and test code There is no need to annotate documentation files.
Annotate only significant size code blocks that can be reviewed on its own e.g., a class, a sequence of methods, a method.
Claiming credit for code blocks smaller than a method is discouraged but allowed. If you do, do it sparingly and only claim meaningful blocks of code such as a block of statements, a loop, or an if-else statement.
- If an enhancement required you to do tiny changes in many places, there is no need to annotate all those tiny changes; you can describe those changes in the Project Portfolio page instead.
- If a code block was touched by more than one person, either let the person who wrote most of it (e.g. more than 80%) take credit for the entire block, or leave it as 'unclaimed' (i.e., no author tags).
- Related to the above point, if you claim a code block as your own, more than 80% of the code in that block should have been written by yourself. For example, no more than 20% of it can be code you reused from somewhere.
- GitHub has a blame feature and a history feature that can help you determine who wrote a piece of code.
Do not try to boost the quantity of your contribution using unethical means such as duplicating the same code in multiple places. In particular, do not copy-paste test cases to create redundant tests. Even repetitive code blocks within test methods should be extracted out as utility methods to reduce code duplication. Individual members are responsible for making sure code attributed to them are correct. If you notice a team member claiming credit for code that he/she did not write or use other questionable tactics, you can email us (after the final submission) to let us know.
If you wrote a significant amount of code that was not used in the final product,
- Create a folder called {project root}/unused
- Move unused files (or copies of files containing unused code) to that folder
- use //@@author {yourGithubUsername}-unused to mark unused code in those files (note the suffix unused) e.g.
```
//@@author johndoe-unused
method 1 ...
method 2 ...
```
Please put a comment in the code to explain why it was not used.
If you reused code from elsewhere, mark such code as //@@author {yourGithubUsername}-reused (note the suffix reused) e.g.
```
//@@author johndoe-reused
method 1 ...
method 2 ...
```
You can use empty @@author tags to mark code as not yours when RepoSense attribute the code to you incorrectly.
- Code generated by the IDE/framework, should not be annotated as your own.
- Code you modified in minor ways e.g. adding a parameter. These should not be claimed as yours but you can mention these additional contributions in the Project Portfolio page if you want to claim credit for them.

Reason 3: Some commits should not be included in the authorship analysis e.g., you committed the code of a third party library by mistake.
Remedy: Let us know the hashes of the commits that need to be omitted from the analysis.

If none of the above works, please please post in the forum or contact us via tic4001@comp.nus.edu.sg so that we can advise you what to do.

We recommend you ensure your code is RepoSense-compatible by v2.0