iP:
Level-5A-PackagestP:
Links → iP Code Dashboard item in the top navigation menu. Click on the </> icon corresponding to a student name to see the code written by that person. We encourage you to read others’ code and learn from them. If you adopt solutions from others (also encouraged), please follow our reuse policy.Admin Module Policies → Policy on Reuse
Reuse is encouraged. However, note that reuse has its own costs (such as the learning curve, additional complexity, usage restrictions, and unknown bugs). Furthermore, you will not be given credit for work done by others. Rather, you will be given credit for reusing work done by others.
Given below are how to give credit for things you reuse from elsewhere. These requirements are specific to this module i.e., not applicable outside the module (outside the module, you should follow the rules specified by your employer and the license of the reused work)
If you used a third party library:
README file (under the Acknowledgements section)If you reused code snippets found on the Internet e.g. from StackOverflow answers or
referred code in another software or
referred project code by current/past student:
//Solution below adapted from https://stackoverflow.com/a/16252290
{Your implmentation of the reused solution here ...}
@@author tags-reused suffix)//@@author {yourGithubUsername}-reused
//{Info about the source...}
{Reused code (possibly with minor modifications) here ...}
//@@author
persons = getList()
//@@author johndoe-reused
//Reused from https://stackoverflow.com/a/34646172 with minor modifications
Collections.sort(persons, new Comparator<CustomData>() {
@Override
public int compare(CustomData lhs, CustomData rhs) {
return lhs.customInt > rhs.customInt ? -1 : 0;
}
});
//@@author
return persons;
@@author tags indicate authorshipMark 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.
<!-- @@author sereneWong -->
<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 ...
*/
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.
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,
{project root}/unused//@@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.
At the end of the project each student is required to submit a Project Portfolio Page.
Team-tasks are the tasks that someone in the team has to do.
Examples of team-tasks
Here is a non-exhaustive list of team-tasks:
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..
docs/team/githbub_username_in_lower_case.md e.g., docs/team/goodcoder123.mdTo 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.
Try the PDF conversion early. If you do it at the last minute, you may not have time to fix any problems in the generated PDF files (such problems are more common than you think).
| Content | Recommended | Hard Limit |
|---|---|---|
| Overview + Summary of contributions | 0.5-1 | 2 |
| [Optional] Contributions to the User Guide | 1 | |
| [Optional] Contributions to the Developer Guide | 3 |
Level-5branch-{increment ID} (e.g. branch-Level-5). You are recommended to have multiple commits in that branch. Follow the branch naming convention exactly or else our gradings scripts might miss your branch.branch-Level-5 back on to master, without a fast-forward so that git creates a separate commit for the merge. git tag that merge commit as Level-5.Level-5: Handle Errors Teach Duke to deal with errors such as incorrect inputs entered by the user.
Example:
todo
____________________________________________________________
☹ OOPS!!! The description of a todo cannot be empty.
____________________________________________________________
blah
____________________________________________________________
☹ OOPS!!! I'm sorry, but I don't know what that means :-(
____________________________________________________________
When implementing this feature, you are also recommended to implement the following extension:
A-PackagesLevel-5 (branch name branch-A-Packages).
Learn the recipe for brainstorming user stories in the textbook → Specifying Requirements → UserStories → Usage.
Also learn about
Follow the steps in the recipe mentioned above to arrive at user stories for the the product, with your team members.
How many user stories? Aim to collect more user stories than you can deliver in the project. Aim to create at least 30 user stories. Include all 'obvious' ones you can think of but also look for 'non obvious' ones that you think are likely to be missed by other competing products.
User stories of what size? Normally, it is fine to use epic-level user stories in the early stages of a project but given this is a small project, you may want to define smaller user stories (i.e., small enough for one person to implement in 1-2 days).
What format?: You may use a sentence format or a table format but do maintain the prescribed three-part structure of a user story. In particular, try to include the benefit part in most user stories as that will come in handy when prioritizing user stories later.
How to record?
Keep records of intermediate steps (e.g., persona, scenarios) in your collaborative project document started in the previous week.
You can write each user story in a piece of paper (e.g. yellow sticky note, index card, or just pieces of paper about the size of a playing card). Alternatively you can use an online tool (some examples given in
Requirements → Gathering Requirements →
Brainstorming: A group activity designed to generate a large number of diverse and creative ideas for the solution of a problem.
In a brainstorming session there are no "bad" ideas. The aim is to generate ideas; not to validate them. Brainstorming encourages you to "think outside the box" and put "crazy" ideas on the table without fear of rejection.
Exercises
Characteristic of brainstorming
What is the key characteristic about brainstorming?
(b)
Requirements → Specifying Requirements →
Can write simple user stories
User story: User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. [Mike Cohn]
A common format for writing user stories is:
User story format: As a {user type/role} I can {function} so that {benefit}
Examples (from a Learning Management System):
You can write user stories on index cards or sticky notes, and arrange them on walls or tables, to facilitate planning and discussion. Alternatively, you can use a software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.
User stories in use
With sticky notes
With paper
[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]
With software
[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]
Exercises
Which of these are true about user stories?
What's wrong with this user story?
Critique the following user story taken from a software project to build an e-commerce website.
As a developer, I want to use Python to implement the software, so that we can reuse existing Python modules.
Refer to the definition of a user story.
User story: User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. [Mike Cohn]
This user story is not written from the perspective of the user/customer.
Extract user stories from customer statement
Bill wants you to build a Human Resource Management (HRM) system. He mentions that the system will help employees to view their own The number of leave days not yet takenleave balance. What are the user stories you can extract from that statement?
Remember to follow the correct format when writing user stories.
User story format: As a {user type/role} I can {function} so that {benefit}
As an employee, I can view my leave balance, so that I can know how many leave days I have left.
Note: the {benefit} part may vary as it is not specifically mentioned in the question.
Can write more detailed user stories
The {benefit} can be omitted if it is obvious.
As a user, I can login to the system so that I can access my data
It is recommended to confirm there is a concrete benefit even if you omit it from the user story. If not, you could end up adding features that have no real benefit.
You can add more characteristics to the {user role} to provide more context to the user story.
You can write user stories at various levels. High-level user stories, called epics (or themes) cover bigger functionality. You can then break down these epics to multiple user stories of normal size.
[Epic] As a lecturer, I can monitor student participation levels
You can add conditions of satisfaction to a user story to specify things that need to be true for the user story implementation to be accepted as ‘done’.
As a lecturer, I can view the forum post count of each student so that I can identify the activity level of students in the forum.
Conditions:
Separate post count for each forum should be shown
Total post count of a student should be shown
The list should be sortable by student name and post count
Other useful info that can be added to a user story includes (but not limited to)
User stories for a travel website (credit: Mike Cohen)
Exercises
Correct statements about user stories
Choose the correct statements
d
Explanation: User stories are short and written in natural language, NOT in a formal language. They are used for estimation and scheduling purposes but do not contain enough details to form a complete system specification.
Can use user stories to manage requirements of project
User stories capture user requirements in a way that is convenient for i.e. which features to include in the productscoping, i.e. how much effort each feature will takeestimation, and i.e. when to deliver each featurescheduling.
[User stories] strongly shift the focus from writing about features to discussing them. In fact, these discussions are more important than whatever text is written. [Mike Cohn, MountainGoat Software 🔗]
User stories differ from e.g. a description of the requirements written in prosetraditional requirements specifications mainly in the level of detail. User stories should only provide enough details to make a reasonably low risk estimate of how long the user story will take to implement. When the time comes to implement the user story, the developers will meet with the customer face-to-face to work out a more detailed description of the requirements. [
User stories can capture
Requirements → Requirements →
Requirements can be divided into two in the following way:
Some examples of non-functional requirement categories:
Some concrete examples of NFRs
You may have to spend an extra effort in digging NFRs out as early as possible because,
Exercises
TEAMMATES NFRs
Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?
(a)(c)(d)(f)(g)
Explanation: (b) are (e) are functions available for a specific user types. Therefore, they are functional requirements. (a), (c), (d), (f) and (g) are either constraints on functionality or constraints on how the project is done, both of which are considered non-functional requirements.
An example of an NFR captured as a user story:
| As a | I want to | so that |
|---|---|---|
| impatient user | to be able experience reasonable response time from the website while up to 1000 concurrent users are using it | I can use the app even when the traffic is at the maximum expected level |
Given their lightweight nature, user stories are quite handy for recording requirements during early stages of requirements gathering.
Given below is a possible recipe you can take when using user stories for early stages of requirement gathering.
Step 0: Clear your mind of preconceived product ideas
Even if you already have some idea of what your product will look/behave like in the end, clear your mind of those ideas. The product is the solution. At this point, we are still at the stage of figuring out the problem (i.e., user requirements). Let's try to get from the problem to the solution in a systematic way, one step at a time.
Step 1: Define the target user as a persona:
Decide your target user's profile (e.g. a student, office worker, programmer, salesperson) and work patterns (e.g. Does he work in groups or alone? Does he share his computer with others?). A clear understanding of the target user will help when deciding the importance of a user story. You can even narrow it down to a persona. Here is an example:
Jean is a university student studying in a non-IT field. She interacts with a lot of people due to her involvement in university clubs/societies. ...
Step 2: Define the problem scope:
Decide the exact problem you are going to solve for the target user. It is also useful to specify what related problems it will not solve so that the exact scope is clear.
ProductX helps Jean keep track of all her school contacts. It does not cover communicating with contacts.
Step 3: List scenarios to form a narrative:
Think of the various scenarios your target user is likely to go through as she uses your app. Following a chronological sequence as if you are telling a story might be helpful.
A. First use:
- Jean gets to know about ProductX. She downloads it and launches it to check out what it can do.
- After playing around with the product for a bit, Jean wants to start using it for real.
- ...
B. Second use: (Jean is still a beginner)
- Jean launches ProductX. She wants to find ...
- ...
C. 10th use: (Jean is a little bit familiar with the app)
- ...
D. 100th use: (Jean is an expert user)
- Jean launches the app and does ... and ... followed by ... as per her usual habit.
- Jean feels some of the data in the app are no longer needed. She wants to get rid of them to reduce clutter.
More examples that might apply to some products:
- Jean uses the app at the start of the day to ...
- Jean uses the app before going to sleep to ...
- Jean hasn't used the app for a while because she was on a three-month training programme. She is now back at work and wants to resume her daily use of the app.
- Jean moves to another company. Some of her clients come with her but some don't.
- Jean starts freelancing in her spare time. She wants to keep her freelancing clients separate from her other clients.
Step 4: List the user stories to support the scenarios:
Based on the scenarios, decide on the user stories you need to support. For example, based on the scenario 'A. First use', you might have user stories such as these:
- As a potential user exploring the app, I can see the app populated with sample data, so that I can easily see how the app will look like when it is in use.
- As a user ready to start using the app, I can purge all current data, so that I can get rid of sample/experimental data I used for exploring the app.
To give another example, based on the scenario 'D. 100th use', you might have user stories such as these:
- As an expert user, I can create shortcuts for tasks, so that I can save time on frequently performed tasks.
- As a long-time user, I can archive/hide unused data, so that I am not distracted by irrelevant data.
Do not 'evaluate' the value of user stories while brainstorming. Reason: an important aspect of brainstorming is not judging the ideas generated.
Other tips:
As a user, I want to see a list of tasks that needs my attention most at the present time, so that I pay attention to them first.While use cases can be recorded on e.g. index cards or sticky notesphysical paper in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not physically in the same locationco-located.
Tool Examples: How to use some example online tools to manage user stories
tool examples
You can create issues for each of the user stories and use a GitHub Project Board to sort them into categories.
Example Project Board:
Example Issue to represent a user story:
You can break the user story into issue subject and description in this way:
| title | As a user I can add a deadline |
|---|---|
| Description | ... so that I can keep track of my deadlines |
Alternatively, you can put the entire user story in the description.
| title | Add deadline |
|---|---|
| Description | As a user I can so that I can keep track of my deadlines |
In both cases, apply the type.Story label.
A video on GitHub Project Boards:
Example Google Sheet for recording user stories:
Example Trello Board for recording user stories:
eXtreme Programming (XP)eXtreme Programming (XP)
Extreme programming (XP) is a software development methodology which is intended to improve software quality and responsiveness to changing customer requirements. As a type of agile software development, it advocates frequent "releases" in short development cycles, which is intended to improve productivity and introduce checkpoints at which new customer requirements can be adopted. [wikipedia, 2017.05.01]
This page in their website explains the difference between user stories and traditional requirements.
One of the biggest misunderstandings with user stories is how they differ from traditional requirements specifications. The biggest difference is in the level of detail. User stories should only provide enough detail to make a reasonably low risk estimate of how long the story will take to implement. When the time comes to implement the story developers will go to the customer and receive a detailed description of the requirements face to face.
Resources
You can create issues for each of the user stories and use a GitHub Project Board to sort them into categories.
Example Project Board:
Example Issue to represent a user story:
You can break the user story into issue subject and description in this way:
| title | As a user I can add a deadline |
|---|---|
| Description | ... so that I can keep track of my deadlines |
Alternatively, you can put the entire user story in the description.
| title | Add deadline |
|---|---|
| Description | As a user I can so that I can keep track of my deadlines |
In both cases, apply the type.Story label.
A video on GitHub Project Boards:
Example Google Sheet for recording user stories:
Example Trello Board for recording user stories:
Intuitively, you might think the right thing to do is to decide what features will be in v2.1 and then plan the intermediate versions based on that. But that's not what we are going to do.
Why? Given the difficulty of reliably estimating the effort each feature will need, any such long-range plan is likely to be inaccurate.
Instead, what we will do is to assume the current iteration is the last iteration, plan that iteration to deliver the product (based on available time), and try to follow that plan as best as we can. After the iteration is over, we plan the next iteration as if it's the last iteration. But that time, you can factor in the experience from the previous iteration to do a better job of planning.
How is that better?
The goal of this activity is to come up with the smallest possible product that is still usable so that it can be implemented as v1.0, to be delivered at the end of the first project iteration. We try to make it small because you will have only two weeks to implement v1.0 and coding as a team is a lot harder than writing code alone.
Do not discuss features, UI, command format, or implementation details yet. That would be like putting the cart before the horse. At this stage we are simply trying to choose which user needs to fulfill first.
Suggested workflow: