A balanced, iterative, and brown-field introduction to Software Engineering...
CS2113/T is an introductory Software Engineering module. It covers roughly a 50-50 balance of basic SE theory and practice that a student needs to know before going for SE internships in the industry or taking
On the theory side, this module is supported by a customized online textbook Software Engineering for Self-Directed Learners, integrated into this module website.
The practice side of this module is mainly covered by a team project. Students are expected to take over an existing project AddressBook-Level4 (AB4) -- a relatively small yet non-trivial (10 KLoC) generic product -- and enhance it into a better product or evolve it into a different product. To help students to tackle the learning curve of working with 10 KLoC of code, the module takes them through a series of projects of increasing size, from AddressBook-Level1(1 KLoC) to AddressBook-Level3(4 KLoC).
Given below is a summary of what the module covers and does not cover (i.e., unticked items).
| Topic | Covered | Not covered |
|---|---|---|
| Java | Used heavily, but not taught extensively | syntax (reason: expected to self-learn) |
| OOP | Used in a non-trivial project,
|
advanced OOP |
| SE tools/practices |
|
those specific to start-ups |
| Modeling |
|
intensive
|
| Requirements |
|
rapid prototyping, heavy UI design, designing a product from scratch |
| Documentation | Documentation targeting end users (example) as well as those targeting developers (example) | Marketing materials |
| Project Management | Iterative delivery of a product, Working collaboratively with team members, on-site as well as remotely | Setting up project infrastructure from scratch |
| Testing |
|
|
| Applications domains | Cross-platform desktop applications | Web programming, Mobile programming, Database programming |
The Schedule pageSchedule page is your main source of information for CS2113/T. You will need to refer to it weekly.
More details for the upcoming weeks (and upcoming sections of the textbook) will be added as the weeks progress. In general, information given for more than 1 week into the future should be treated as tentative.
💡 For those who don't like the nested-info style used by this website, we have also provided flat all-in-one versions of the textbook and the admin info.
Most of this will work on most mainstream Browsers, but embedded slides are best viewed using Chrome.
This book tries to layer information so that readers can decide to omit less important layers if they wish to.
More important information are in bold or highlighted while less important information are dimmed or in collapsed panels such as the below.
Less important info
Less important info
Less important info
Tabs indicate alternative formats of the same content (e.g. video vs text). You can choose the one you like and ignore the other tabs.
Video describing X
Dotted underlines indicate
This website uses a star rating system to indicate the priority level of contents.
Relevant: [
Start with things that are rated one-star and progress to things with more stars. Things rated four stars are optional.
Star ratings for Learning Outcomes (and textbook sections):
One-star LOs : The LOs you need to achieve just to keep up with the module. We recommend you to achieve these LOs if you want to pass the module (i.e. up to a C grade).
Two-stars LOs : Can get you up to a B+.
Three-stars LOs : Can get you up to an A.
Four-stars LOs : Can be useful for getting an A+, tutors positions, and getting into downstream SE modules that have competitive entry requirements (e.g., CS3281&2, CS3217, CS3216). Four-star LOs are not examinable. Omitting them will not affect your CAP (as A+ has the same CAP as an A grade)
LOs marked with two icons e.g., : , : , : , : are relevant LOs you are expected have achieved in prerequisite modules. They are given for reference and are examinable. The number of stars indicate the progression of topics, similar to the star rating system above i.e., one-star prerequisite LOs are the most basic and the most important. Four-star pre-requisite LOs can be ignored without affecting CAP.
Star ratings for other things e.g., admin info sections:
Meaning of some shortened headings:
What : the meaning of the concept in concern
Why : the motivation behind the concept in concern
How : the usage of the concept in concern
When : the pros and cons of the concept in concern, when to use the concept
tangential : tangential info, can be ignored if not interested
: direct link to the LO. Ctrl+Click to open the LO in new window/tab.
: learning outcomes
: prerequisite learning outcome
: examples
: resources
: exercises
: printable version
: preview/more info
: video
: textual description
: slides
: output produced by running code
question without answer
question with answer
: tasks to do
: lecture
: tutorial
: evidence you can use to prove you have achieved a learning outcome
⏰ : deadline
Use the search box in the top navigation bar to search for keywords in the website pages. If you cannot find the content related to a keyword, let us know by posting in the website issue tracker so that we can add the missing keyword to our search index.
Use Chrome to load the page you want to save as pdf.
Click on the Print option in Chrome’s menu.
Set the destination to Save as PDF, then click Save to save a copy of the file in PDF format. For best results, use the settings indicated in the screenshot below.
Printer-friendly version (indicated by icon) have been provided for each chapter and the whole book. You can use them for saving as pdf files or printing.
This website was generated using the MarkBind software developed at NUS. We welcome bug reports, suggestions, and contributions, to be submitted at the website issue tracker.
This module requires you to write Java code almost every week, starting from the very first week. While we introduce some bit of Java programming in this module, it is by no means exhaustive. The module expects that you learn much of Java programming by yourself.
In particular, you may want to have a look at the new features introduced in Java 8 such as streams, lambdas, Optionals. These are used in the codebase given to you.
Given 60% of this module is based on CA, it can appear to be heavy. However, it is not expected that you will spend more time on this module than its peer modules (e.g., if this module is core for you, it should not take more time than other level 2 core modules in your program).
Start with things that are rated one-star and progress to things with more stars. Things rated four stars are optional.
Star ratings for Learning Outcomes (and textbook sections):
One-star LOs : The LOs you need to achieve just to keep up with the module. We recommend you to achieve these LOs if you want to pass the module (i.e. up to a C grade).
Two-stars LOs : Can get you up to a B+.
Three-stars LOs : Can get you up to an A.
Four-stars LOs : Can be useful for getting an A+, tutors positions, and getting into downstream SE modules that have competitive entry requirements (e.g., CS3281&2, CS3217, CS3216). Four-star LOs are not examinable. Omitting them will not affect your CAP (as A+ has the same CAP as an A grade)
LOs marked with two icons e.g., : , : , : , : are relevant LOs you are expected have achieved in prerequisite modules. They are given for reference and are examinable. The number of stars indicate the progression of topics, similar to the star rating system above i.e., one-star prerequisite LOs are the most basic and the most important. Four-star pre-requisite LOs can be ignored without affecting CAP.
Star ratings for other things e.g., admin info sections:
📆 [Friday (previous week)]
Attend the lecture for,
Relevant: [
Timing/venue:
| Semester | Venue | Time |
|---|---|---|
| Semester 1 (Aug-Nov) | LT15 | Friday 1600-1800 |
| Semester 2 (Jan-April) | COM1-0212 | Wednesday 1200-1400 |
Lectures start on time sharp and end around 15 minutes before official end time.
CS2113T lectures are same as that for CS2113. Please ignore the CS2101 session scheduled at the same slot. That is a dummy slot used to work around a limitation on the CORS IT system. The system doesn't allow lectures of two modules to be scheduled in the same venue at the same time.
Attendance: Attendance for the first lecture is compulsory.
Webcast: All lectures will be webcast. However, some things are not captured well in the webcast recording. You are advised to treat the webcast as a 'backup' for you to catch up anything missed during the lecture.
Handouts: There are no handouts. All learning materials are organized around learning outcomes (not lectures or topics), are given in Web format, and can be found in the Textbook section and are also hyperlinked from the Schedule pageSchedule page.
Slides: Our lecture slides are not suited for printing or using as a reference during the lecture/exams. They are only an aid for lecture delivery. Slides will be uploaded after the lecture (link available in the Schedule pageSchedule page).
📆 [Saturday (previous week) - Tuesday]
Relevant: [
This module is organized primarily around a list of Learning Outcomes.
Each week has a suggested list of LOs. They are categorized using a star-rating system (see below).
Relevant: [
Start with things that are rated one-star and progress to things with more stars. Things rated four stars are optional.
Star ratings for Learning Outcomes (and textbook sections):
One-star LOs : The LOs you need to achieve just to keep up with the module. We recommend you to achieve these LOs if you want to pass the module (i.e. up to a C grade).
Two-stars LOs : Can get you up to a B+.
Three-stars LOs : Can get you up to an A.
Four-stars LOs : Can be useful for getting an A+, tutors positions, and getting into downstream SE modules that have competitive entry requirements (e.g., CS3281&2, CS3217, CS3216). Four-star LOs are not examinable. Omitting them will not affect your CAP (as A+ has the same CAP as an A grade)
LOs marked with two icons e.g., : , : , : , : are relevant LOs you are expected have achieved in prerequisite modules. They are given for reference and are examinable. The number of stars indicate the progression of topics, similar to the star rating system above i.e., one-star prerequisite LOs are the most basic and the most important. Four-star pre-requisite LOs can be ignored without affecting CAP.
Star ratings for other things e.g., admin info sections:
📆 [Wednesday - Friday]
Attend the tutorial to,
Relevant: [
Our tutorials start on week 2 (even before CORS tutorial bidding is over), not in week 3 as other modules do. CS2113 (not CS2113T) students need to choose a temporary tutorial slot for week 2 tutorial. We'll inform you the procedure to do so in due course.
Our tutorial IDs are different from CORS. Format: W12 means Wednesday 1200 and so on.
| Module | Tutorial ID (ID in CORS) | Time | Venue | Tutors (contact details) |
|---|---|---|---|---|
| CS2113T | W12 (1) | Wed 1200 | COM1-B103 | TBD |
| CS2113T | W13 (2) | Wed 1300 | COM1-B103 | TBD |
| CS2113T | T09 (3) | Thu 0900 | COM1-B103 | TBD |
| CS2113T | T12 (4) | Thu 1200 | COM1-B103 | TBD |
| CS2113T | F09 (5) | Fri 0900 | COM1-B103 | TBD |
| CS2113T | F10 (6) | Fri 1000 | COM1-B103 | TBD |
| CS2113 | T13 (1) | Thu 1300 | COM1-B103 | TBD |
| CS2113 | T16 (2) | Thu 1600 | COM1-B103 | TBD |
What happens during the tutorial:
Relevant: [
If you do not have a laptop or prefer not to bring the laptop, it is up to you to show your work to the tutor in some way (e.g. by connecting to your home PC remotely), without requiring extra time/effort from the tutor or team members.
Reason: As you enjoy the benefits of not bring the laptop; you (not others) should bear the cost too.
The role of our tutors is different from tutors in other modules.
Relevant: [
This guide is mostly about getting tech help, but it also applies to getting clarifications on module topics too. e.g. what is the difference between refactoring and rewriting?
We want to move you away from 'hand holding' and make you learn how to solve problems on your own. This is a vital survival skill in the industry and it needs practice.
Whether it is a technical problem (e.g. error when using the IDE) or a doubt about a concept (e.g. what is the difference between scripted testing and exploratory testing?) the teaching team is happy to work with you when you look for a solution/answer, but we do not do it for you. We discourage unconditional direct help from tutors because we want you to learn to help yourself. Yes, we believe in ‘tough love’😝.
The question you should always ask yourself is, 'how do I solve this problem if the lecturer/tutors are not around to help me?'
What not to do:
What to do:
Check what is given: Check if the problem/concept has been discussed in the lectures, textbook, or the list of resources given to you. Yes, it is easier for you to write an email to the tutor/lecturer instead, but that shouldn't be your default behavior. We know that sometimes it is difficult to find stuff in the resources we have provided. But you should try first.
Search: It is very likely the answer already exists somewhere in the cyberspace. Almost every programming-related question has been answered in places like stackoverflow.
Don't give an opportunity for someone to ask you to STFW.
Pay attention to the error message you encounter. Sometimes it also contains hints as to how to fix the problem. Even
if not, a web search on the error message is a good starting point.
Ask peers:
Ask your team members.
Ask classmates using the module forum or the slack channel. Even if you figured out one way to solve a problem, discussing it on a public forum might lead you to better ways of solving it, and will help other classmates who are facing similar problems too. If you are really shy to ask questions in the forum, you may use this form to submit your question anonymously which we will then post in the forum.
Rubber duck debugging is an informal term used in software engineering to refer to a method of debugging code. The name is a reference to a story in the book The Pragmatic Programmer in which a programmer would carry around a rubber duck and debug his code by forcing himself to explain it, line-by-line, to the duck.
[for more, see wikipedia entry]
Ask the world using programming forums such as stackoverflow.
Here are some tips for posting help request:
PLEASE search for existing answers before you post your question in those public forums; You don't want to appear as a 'clueless' or 'too lazy to do your research' person in a public forum.
Learn to isolate the problem. "My code doesn't work" isn't going to help even if you post the whole code online. Others don't have time to go through all of your code. Isolate the part that doesn't work and strip it down to the bare minimum that is enough reproduce the error. Sometimes, this process actually helps you to figure out the problem yourself. If not, at least it increases the chance of someone else being able to help you.
💡 How to isolate problematic code? Delete code (one bit at a time) that is confirmed as not related to the problem. Do that until you can still reproduce the problem with the least amount of code remaining.
Generalize the problem. "How to write tasks to a text file using Java" is too specific to what you are working on. You are more likely to find help if you post a thread called (or search for) "How to write to a file using Java".
Explain well. Conversations via online forums take time. If you post everything that is relevant to your problem, your chances of getting an answer in the first try is higher. If others have to ask you more questions before they can help you, it will take longer. But this doesn't mean you dump too much information into the thread either.
💡 Know what these stand for: RTFM, STFW, GIYF
Talk to the lecturer before or after the lecture. The lecturer will be at the lecture venue from 30 minutes before the start of the lecture.
Request our help: Failing all above, you can always request for help by emailing the lecturer.
Resources
Relevant: [
Timing/venue:
Grading:
Tutorials are not graded. However, your conduct will be reviewed by team members and the tutor which will determine your participation marks.
[Exchange students only] Registering for tutorials:
This module is organized primarily around a list of Learning Outcomes.
Each week has a suggested list of LOs. They are categorized using a star-rating system (see below).
Relevant: [
Start with things that are rated one-star and progress to things with more stars. Things rated four stars are optional.
Star ratings for Learning Outcomes (and textbook sections):
One-star LOs : The LOs you need to achieve just to keep up with the module. We recommend you to achieve these LOs if you want to pass the module (i.e. up to a C grade).
Two-stars LOs : Can get you up to a B+.
Three-stars LOs : Can get you up to an A.
Four-stars LOs : Can be useful for getting an A+, tutors positions, and getting into downstream SE modules that have competitive entry requirements (e.g., CS3281&2, CS3217, CS3216). Four-star LOs are not examinable. Omitting them will not affect your CAP (as A+ has the same CAP as an A grade)
LOs marked with two icons e.g., : , : , : , : are relevant LOs you are expected have achieved in prerequisite modules. They are given for reference and are examinable. The number of stars indicate the progression of topics, similar to the star rating system above i.e., one-star prerequisite LOs are the most basic and the most important. Four-star pre-requisite LOs can be ignored without affecting CAP.
Star ratings for other things e.g., admin info sections:
Timing/venue:
| Semester | Venue | Time |
|---|---|---|
| Semester 1 (Aug-Nov) | LT15 | Friday 1600-1800 |
| Semester 2 (Jan-April) | COM1-0212 | Wednesday 1200-1400 |
Lectures start on time sharp and end around 15 minutes before official end time.
CS2113T lectures are same as that for CS2113. Please ignore the CS2101 session scheduled at the same slot. That is a dummy slot used to work around a limitation on the CORS IT system. The system doesn't allow lectures of two modules to be scheduled in the same venue at the same time.
Attendance: Attendance for the first lecture is compulsory.
Webcast: All lectures will be webcast. However, some things are not captured well in the webcast recording. You are advised to treat the webcast as a 'backup' for you to catch up anything missed during the lecture.
Handouts: There are no handouts. All learning materials are organized around learning outcomes (not lectures or topics), are given in Web format, and can be found in the Textbook section and are also hyperlinked from the Schedule pageSchedule page.
Slides: Our lecture slides are not suited for printing or using as a reference during the lecture/exams. They are only an aid for lecture delivery. Slides will be uploaded after the lecture (link available in the Schedule pageSchedule page).
Our tutorials start on week 2 (even before CORS tutorial bidding is over), not in week 3 as other modules do. CS2113 (not CS2113T) students need to choose a temporary tutorial slot for week 2 tutorial. We'll inform you the procedure to do so in due course.
Our tutorial IDs are different from CORS. Format: W12 means Wednesday 1200 and so on.
| Module | Tutorial ID (ID in CORS) | Time | Venue | Tutors (contact details) |
|---|---|---|---|---|
| CS2113T | W12 (1) | Wed 1200 | COM1-B103 | TBD |
| CS2113T | W13 (2) | Wed 1300 | COM1-B103 | TBD |
| CS2113T | T09 (3) | Thu 0900 | COM1-B103 | TBD |
| CS2113T | T12 (4) | Thu 1200 | COM1-B103 | TBD |
| CS2113T | F09 (5) | Fri 0900 | COM1-B103 | TBD |
| CS2113T | F10 (6) | Fri 1000 | COM1-B103 | TBD |
| CS2113 | T13 (1) | Thu 1300 | COM1-B103 | TBD |
| CS2113 | T16 (2) | Thu 1600 | COM1-B103 | TBD |
What happens during the tutorial:
Relevant: [
If you do not have a laptop or prefer not to bring the laptop, it is up to you to show your work to the tutor in some way (e.g. by connecting to your home PC remotely), without requiring extra time/effort from the tutor or team members.
Reason: As you enjoy the benefits of not bring the laptop; you (not others) should bear the cost too.
The role of our tutors is different from tutors in other modules.
Relevant: [
This guide is mostly about getting tech help, but it also applies to getting clarifications on module topics too. e.g. what is the difference between refactoring and rewriting?
We want to move you away from 'hand holding' and make you learn how to solve problems on your own. This is a vital survival skill in the industry and it needs practice.
Whether it is a technical problem (e.g. error when using the IDE) or a doubt about a concept (e.g. what is the difference between scripted testing and exploratory testing?) the teaching team is happy to work with you when you look for a solution/answer, but we do not do it for you. We discourage unconditional direct help from tutors because we want you to learn to help yourself. Yes, we believe in ‘tough love’😝.
The question you should always ask yourself is, 'how do I solve this problem if the lecturer/tutors are not around to help me?'
What not to do:
What to do:
Check what is given: Check if the problem/concept has been discussed in the lectures, textbook, or the list of resources given to you. Yes, it is easier for you to write an email to the tutor/lecturer instead, but that shouldn't be your default behavior. We know that sometimes it is difficult to find stuff in the resources we have provided. But you should try first.
Search: It is very likely the answer already exists somewhere in the cyberspace. Almost every programming-related question has been answered in places like stackoverflow.
Don't give an opportunity for someone to ask you to STFW.
Pay attention to the error message you encounter. Sometimes it also contains hints as to how to fix the problem. Even if
not, a web search on the error message is a good starting point.
Ask peers:
Ask your team members.
Ask classmates using the module forum or the slack channel. Even if you figured out one way to solve a problem, discussing it on a public forum might lead you to better ways of solving it, and will help other classmates who are facing similar problems too. If you are really shy to ask questions in the forum, you may use this form to submit your question anonymously which we will then post in the forum.
Rubber duck debugging is an informal term used in software engineering to refer to a method of debugging code. The name is a reference to a story in the book The Pragmatic Programmer in which a programmer would carry around a rubber duck and debug his code by forcing himself to explain it, line-by-line, to the duck.
[for more, see wikipedia entry]
Ask the world using programming forums such as stackoverflow.
Here are some tips for posting help request:
PLEASE search for existing answers before you post your question in those public forums; You don't want to appear as a 'clueless' or 'too lazy to do your research' person in a public forum.
Learn to isolate the problem. "My code doesn't work" isn't going to help even if you post the whole code online. Others don't have time to go through all of your code. Isolate the part that doesn't work and strip it down to the bare minimum that is enough reproduce the error. Sometimes, this process actually helps you to figure out the problem yourself. If not, at least it increases the chance of someone else being able to help you.
💡 How to isolate problematic code? Delete code (one bit at a time) that is confirmed as not related to the problem. Do that until you can still reproduce the problem with the least amount of code remaining.
Generalize the problem. "How to write tasks to a text file using Java" is too specific to what you are working on. You are more likely to find help if you post a thread called (or search for) "How to write to a file using Java".
Explain well. Conversations via online forums take time. If you post everything that is relevant to your problem, your chances of getting an answer in the first try is higher. If others have to ask you more questions before they can help you, it will take longer. But this doesn't mean you dump too much information into the thread either.
💡 Know what these stand for: RTFM, STFW, GIYF
Talk to the lecturer before or after the lecture. The lecturer will be at the lecture venue from 30 minutes before the start of the lecture.
Request our help: Failing all above, you can always request for help by emailing the lecturer.
Resources
Relevant: [
Timing/venue:
Grading:
Tutorials are not graded. However, your conduct will be reviewed by team members and the tutor which will determine your participation marks.
[Exchange students only] Registering for tutorials:
This module is supported by a customized online text book **Software Engineering for Self-Directed Learners*, integrated into this module website. While it is in a dynamic Web page format, there is a way to save the main text as pdf files. Printer-friendly versions have been provided too.
Relevant: [
Use Chrome to load the page you want to save as pdf.
Click on the Print option in Chrome’s menu.
Set the destination to Save as PDF, then click Save to save a copy of the file in PDF format. For best results, use the settings indicated in the screenshot below.
 |
The main language used in this module is Java. You should use Java for all programming activities, the project, and exam answers. The module doesn’t “teach” Java, but only introduces some topics essential to get you started. We expect you to learn on your own any Java constructs that are not covered in the lectures, but used in the provided codebase. |
This module follows the OSS-NUS Java coding standard.
In the project you are required to follow basic and intermediate guidelines (those marked as ⭐️ and ⭐️⭐️). In other programming activities in the module, we recommend (but not require) you to follow the coding standard.
The high-level learning outcome of the project (and to a large degree, the entire module):
Accordingly, the module project is structured to resemble an intermediate stage of a non-trivial real-life software project. In this project you will,
In this semester, we are going to enhance an AddressBook application.
This product is meant for users who can type fast, and prefer typing over mouse/voice commands. Therefore, Command Line Interface (CLI) is the primary mode of input.
Relevant: [
[Direction 1] Optimize AddressBook for a more specific target user group:
An AddressBook,
[Direction 2] Morph AddressBook into a different product: Given that AddressBook is a generic app that manages a type of elements (i.e. contacts), you can use it as a starting point to create an app that manages
something else.
❗️ This is a high-risk high-reward option because morphing requires extra work but a morphed product may earn more marks than an optimized product of similar complexity.
An app to manage,
For either direction, you need to define a target user profile and a value proposition:
Target user profile: Define a very specific target user profile.
💡 We require you to narrow down the target user profile as opposed to trying to make it as general as possible. Here is an example direction of narrowing down target user: anybody → teachers → university teachers → tech savvy university teachers → CS2113/T instructors.
❗️ Be careful not to contradict given project constraints when defining the user profile e.g. the target user should still prefer typing over mouse actions.
It is expected that your product will be optimized for the chosen target users i.e., add features that are especially/only applicable for target users (to make the app especially attractive to them). w.r.t. the example above, there can be features that are applicable to CS2113/T instructors only, such as the ability to navigate to a student's project on GitHub 💡 Your project will be graded based on how well the features match the target user profile and how well the features fit-together.
Individually, each student is expected to,
Contribute one enhancement to the product
Each enhancement should be stand-alone but,
Here are some examples of different major enhancements and the grade the student is likely to earn for the relevant parts of the project grade.
A) : Add support for undo/redoB) : Add support for viewing historyIn the initial stages of the project you are recommended to add minor enhancements in order to get familiar with the project. These minor enhancements are unlikely to earn marks. You are advised not to spend a lot of effort on minor enhancements.
Here is a non-exhaustive list of minor enhancements:
Recommended: contribute to all aspects of the project: e.g. write backend code, frontend code, test code, user documentation, and developer documentation. If you limit yourself to certain aspects only, you will lose marks
allocated for the aspects you did not do.
In particular, you are required to divide work based on features rather than components:
Do a share of team-tasks: These are the tasks that someone in the team has to do. Marks allocated to team-tasks will be divided among team members based on how much each member contributed to those tasks.
Here is a non-exhaustive list of team-tasks:
Share roles and responsibilities of the project.
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.
Model, UI, Storage, etc. If you are in charge of a component, you are expected to know that component well, and
review changes done to that component in v1.3-v1.4.Please make sure 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.
Write ~300-500 LoC of code, on average.
As a team, you are expected to work together to,
Your project should comply with the following constraints. Reason: to increase comparability among projects and to maximize applicability of module learning outcomes in the project.
Constraint-Morph: The final product should be a result of morphing the given code base. i.e. enhance and/or evolve the given code to arrive at the new software. However, you are allowed to replace all existing code with
new code, as long as it is done incrementally. e.g. one feature/component at a time
Reason: To ensure your code has a decent quality level from the start.
Constraint-Incremental: The product needs to be developed incrementally over the project duration. While it is fine to do less in some weeks and more in other weeks, a reasonably consistent delivery rate is expected. For example, it is not acceptable to do the entire project over the recess week and do almost nothing for the remainder of the semester. Reasons: 1. To simulate a real project where you have to work on a code base over a long period, possibly with breaks in the middle. 2. To learn how to deliver big features in small increments.
Constraint-Human-Editable-File: The data should be stored locally and should be in a human editable text file.
Reason: To allow advanced users to manipulate the data by editing the data file.
Constraint-OO: The software should follow the Object-oriented paradigm.
Reason: For you to practice using OOP in a non-trivial project.
Constraint-No-DBMS: Do not use a
Reason: Using a DBMS to store data will reduce the room to apply OOP techniques to manage data. It is true that most real world systems use a DBMS, but given the small size of this project, we need to optimize it for CS2113/T module learning outcomes; covering DBMS-related LOs will have to be left to database modules or level 3 project modules.
Constraint-Platform-Independent: The software should work on the Windows, Linux, and OS-X platforms. Even if you are unable to manually test the app on all three platforms, consciously avoid using OS-dependent libraries
and OS-specific features.
Reason: Peer testers should be able to use any of these platforms.
Constraint-No-Installer: The software should work without requiring an installer. Having an optional installer is OK as long as the portable (non-installed) version has all the critical functionality.
Reason: We do not want to install all your projects on our testing machines when we test them for grading.
Constraint-External-Software: The use of third-party frameworks/libraries is allowed but only if they,
and is subjected to prior approval by the teaching team.
Reason: We will not allow third-party software that can interfere with the learning objectives of the module.
Please post in the forum your request to use a third-party libraries before you start using the library. Once a specific library has been approved for
one team, other teams may use it without requesting permission again.
Reason: The whole class should know which external software are used by others so that they can do the same if they wish to.
[Picture: The team that was at the top of early Google]
When to form teams
Team size: The default team size is five.
Team ID: This will be given to you after forming teams. It has the form TUTORIAL_ID-TEAM_NUMBER e.g, W12-2 means you are in tutorial W12 (i.e., Wed 1200-1300), team 2.
Relevant: [
Our tutorials start on week 2 (even before CORS tutorial bidding is over), not in week 3 as other modules do. CS2113 (not CS2113T) students need to choose a temporary tutorial slot for week 2 tutorial. We'll inform you the procedure to do so in due course.
Our tutorial IDs are different from CORS. Format: W12 means Wednesday 1200 and so on.
| Module | Tutorial ID (ID in CORS) | Time | Venue | Tutors (contact details) |
|---|---|---|---|---|
| CS2113T | W12 (1) | Wed 1200 | COM1-B103 | TBD |
| CS2113T | W13 (2) | Wed 1300 | COM1-B103 | TBD |
| CS2113T | T09 (3) | Thu 0900 | COM1-B103 | TBD |
| CS2113T | T12 (4) | Thu 1200 | COM1-B103 | TBD |
| CS2113T | F09 (5) | Fri 0900 | COM1-B103 | TBD |
| CS2113T | F10 (6) | Fri 1000 | COM1-B103 | TBD |
| CS2113 | T13 (1) | Thu 1300 | COM1-B103 | TBD |
| CS2113 | T16 (2) | Thu 1600 | COM1-B103 | TBD |
Team composition
We allow some freedom in choosing team members, subject to these constraints:
All team members should be in the same tutorial. Delay forming teams until your place in a tutorial is confirmed. We do not allow changing tutorials to team up with your preferred team mates.
Teams of single nationality are not allowed Rationale: to train you to work in multicultural teams. However, we allow same nationality teams if the only language common among all team members is English. e.g. an all-Singaporean team that include both Chinese and Malay students.
No more than one exchange students per team Rationale: to increase interaction between exchange students and NUS students.
Gender balanced teams are encouraged. While all-male teams may be unavoidable at times (due to high male percentage in the cohort), all-female teams are highly discouraged.
Also note that we may modify teams when circumstances call for it. There is no avenue for you to object. Staying with your preferred team is not guaranteed.
To expedite your project implementation, you will be given some sample code (AddressBook-Level1 to AddressBook-Level4, shown as AB1 to AB4 in the diagram above). You can use AB1 to AB3 to
ramp up your tech skills in preparation for the project. AB4 is to be used as the basis for your project.
AB4 is the version you will use as the starting point for your final project. Some of the work you do in AB1 to AB3 can be ported over to AB4 and can be used to claim credit in the final
project.
Given below is the high-level timeline of the project.
| Week | Stage | Activities |
|---|---|---|
| 3 | inception | Decide on a overall project direction (user profile, problem addressed, optimize or morph?). |
| 4 | mid-v1.0 | Decide on requirements (user stories, use cases, non-functional requirements). |
| 5 | v1.0 | Conceptualize product and document it as a user guide(draft), draft a rough project plan. |
| 6 | mid-v1.1 | Set up project repo, start moving UG and DG to the repo, attempt to do local-impact changes to the code base. |
| 7 | v1.1 | Update UG and DG in the repo, update project plan in repo, attempt to do global-impact changes to the code base. |
| 8 | mid-v1.2 | Adjust project schedule/rigor as needed, complete repo set up, start proper milestone management. |
| 9 | v1.2 | Move code towards v2.0 in small steps, start documenting design/implementation details in DG. |
| 10 | mid-v1.3 | Continue to enhance features. Make code RepoSense-compatible. Try doing a proper release. |
| 11 | v1.3 | Release as a jar file, release updated user guide, peer-test released products, verify code authorship. |
| 12 | mid-v1.4 | Tweak as per peer-testing results, draft Project Portfolio Page, practice product demo. |
| 13 | v1.4 | Final tweaks to docs/product, release product, demo product, evaluate peer projects. |
More details of each stage is provided elsewhere is this website.
Overview: Decide on a overall project direction (user profile, problem addressed, optimize or morph?).
This is a good time to analyze requirements with a view to conceptualizing the next version of the product (i.e. v2.0).
Set up a weekly project meeting time/venue with your team members
We recommend at least one face-to-face project meeting per week. The project meeting time can be used to discuss project related things, but also, can be used as a time for team members to work on the project tasks individually (having all members in the same place will facilitate easier collaboration and more peer-learning).
Play around with AB4
Download the latest released version (i.e., the jar file) of AB4 from its upstream repo and play around with it to familiarize with its current features.
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
In general, each team is expected to take one of these two directions:
[Direction 1] Optimize AddressBook for a more specific target user group:
An AddressBook,
[Direction 2] Morph AddressBook into a different product: Given that AddressBook is a generic app that manages a type of elements (i.e. contacts), you can use it as a starting point to create an app that
manages something else.
❗️ This is a high-risk high-reward option because morphing requires extra work but a morphed product may earn more marks than an optimized product of similar complexity.
An app to manage,
For either direction, you need to define a target user profile and a value proposition:
Target user profile: Define a very specific target user profile.
💡 We require you to narrow down the target user profile as opposed to trying to make it as general as possible. Here is an example direction of narrowing down target user: anybody → teachers → university teachers → tech savvy university teachers → CS2113/T instructors.
❗️ Be careful not to contradict given project constraints when defining the user profile e.g. the target user should still prefer typing over mouse actions.
It is expected that your product will be optimized for the chosen target users i.e., add features that are especially/only applicable for target users (to make the app especially attractive to them). w.r.t. the example above, there can be features that are applicable to CS2113/T instructors only, such as the ability to navigate to a student's project on GitHub 💡 Your project will be graded based on how well the features match the target user profile and how well the features fit-together.
Given below are some guidance on the recommended progress at this point of the project (i.e., at week 4, which is the midway point of the milestone v1.0)
Overview: Decide on requirements (user stories, use cases, non-functional requirements).
This is a good time to analyze requirements with a view to conceptualizing the next version of the product (i.e. v2.0).
Step 1 : Brainstorm user stories
Get together with your team members and
It is ok to have 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 teams.
Refer
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
Note that you should not 'evaluate' the value of user stories while doing the above. Reason: an important aspect of brainstorming is not judging the ideas generated.
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.
What is the key characteristic about brainstorming?
(b)
Requirements → Specifying Requirements → 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):
We can write user stories on index cards or sticky notes, and arrange on walls or tables, to facilitate planning and discussion. Alternatively, we can use a software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.
[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]
[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]
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 resue 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.
Bill wants you to build a Human Resource Management (HRM) system. He mentions that the system will help employees to view their own
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.
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:
A video on GitHub Project Boards:
Example Google Sheet for recording user stories:
Example Trello Board for recording user stories:
Given their lightweight nature, user stories are quite handy for recording requirements during early stages of requirements gathering.
💡 Here are some tips for using user stories for early stages of requirement gathering:
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.As a user I can add a task by specifying a task description only, so that I can record tasks that need to be done ‘some day’.
As a user I can find upcoming tasks, so that I can decide what needs to be done soon.
As a user I can delete a task, so that I can get rid of tasks that I no longer care to track.
As a new user I can view more information about a particular command, so that I can learn how to use various commands.
As an advanced user I can use shorter versions of a command, so that type a command faster.
Step 2: Prioritize the user stories
Suggested workflow:
Take one user story at a time and get team member opinions about it.
Based on the team consensus, put the story (i.e. the piece of paper) onto one of these three piles:
Must-Have : The product will be practically useless to the target user without this feature.Nice-To-Have : The target user can benefit from this user story significantly but you are not certain if you'll have time to implement it.Not-Useful : No significant benefit to the target user, or does not fit into the product vision.If using physical paper to record user stories: After all stories have been put in the above three piles, you can make a record of which stories are in the three piles.
Step 3: Document requirements of the product
Based on your user story categorization in the step above, given module requirements/constraints for the project, and the current state of the product, select which user stories you are likely to include in v2.0.
Document the following items using a convenient format (e.g., a GoogleDoc). Do not spend time on formatting the content nicely; reason: these will be ported to the actual Developer Guide in your project repo later.
💡 Some examples of these can be found in the AB4 Developer Guide.
Requirements → Specifying Requirements → Use Cases →
Use Case: A description of a set of sequences of actions, including variants, that a system performs to yield an observable result of value to an
Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.
A use case describes an interaction between the user and the system for a specific functionality of the system.
Unified Modeling Language (UML) is a graphical notation to describe various aspects of a software system. UML is the brainchild of three software modeling specialists James Rumbaugh, Grady Booch and Ivar Jacobson (also known as the Three Amigos). Each of them has developed their own notation for modeling software systems before joining force to create a unified modeling language (hence, the term ‘Unified’ in UML). UML is currently the de facto modeling notation used in the software industry.
Use cases capture the functional requirements of a system.
Requirements → Requirements →
There are two kinds of requirements:
Some examples of non-functional requirement categories:
We may have to spend an extra effort in digging NFRs out as early as possible because,
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.
Requirements → Specifying Requirements → Glossary →
Glossary: A glossary serves to ensure that all stakeholders have a common understanding of the noteworthy terms, abbreviation, acronyms etc.
Here is a partial glossary from a variant of the Snakes and Ladders game:
Requirements → Gathering Requirements →
Studying existing products can unearth shortcomings of existing solutions that can be addressed by a new product. Product manuals and other forms of technical documentation of an existing system can be a good way to learn about how the existing solutions work.
When developing a game for a mobile device, a look at a similar PC game can give insight into the kind of features and interactions the mobile game can offer.
Overview: Conceptualize product and document it as a user guide(draft), draft a rough project plan.
v1.0 Summary of Milestone
Here is a summary of items you need to deliver to reach v1.0 individual () and team () milestones. See sections below for more details of each item.
| Milestone | Minimum acceptable performance to consider as 'reached' |
|---|---|
| requirements documented | a draft of v2.0 requirements in some form |
| [optional] product survey documented | none |
| v2.0 conceptualized | a draft of v2.0 user guide in some form |
| feature releases planned | a rough feature release plan |
❗️ Reaching individual and team milestones are considered for grading the project management component of your project grade (expand the panel below for more info).
❗️ The deadline for reaching a milestone is the midnight before your tutorial e.g., if your tutorial is on Wednesday, you need to reach the milestone by Tuesday midnight.
Relevant: [
A. Process:
Evaluates: How well you did in project management related aspects of the project, as an individual and as a team
Based on: Supervisor observations of project milestones and GitHub data.
Milestones need to be reached the midnight before of the tutorial for it to be counted as achieved. To get a good grade this aspect, achieve recommended weekly progress in at least 6/10 weeks.
Other criteria:
B. Team-based tasks:
Evaluates: How much you contributed to common team-based tasks
Based on: peer evaluations and tutor observations
Relevant: [
Here is a non-exhaustive list of team-tasks:
Developer Guide: Have a draft of the requirements of your project, as described in mid-v1.0 progress guide.
User Guide:
Draft a user guide in a convenient format (e.g., a GoogleDoc) to describe what the product would be like when it is at 2.0. We recommend that you follow the existing
💡 It is highly recommended that you divide documentation work (in the User Guide and the Developer Guide) among team members based on enhancements/features each person would be adding e.g., If you are the person planing to add a feature X, you should be the person to describe the feature X in the User Guide and in the Developer Guide. For features that are not planned to be implemented by v1.4, you can divide them based on who will be implementing them if the project were to continue until v2.0 (hypothetically).
Reason: In the final project evaluation your documentation skills will be graded based on sections of the User/Developer Guide you have written.
Suggested length: Follow the existing user guide and developer guides in terms of the level of details.
Submission: Save your draft a single pdf file, name it {Your Team ID}.pdf e.g., W09-3.pdf and upload to IVLE.
Submission: Include in the pdf file you upload to IVLE.
Overview: Set up project repo, start moving UG and DG to the repo, attempt to do local-impact changes to the code base.
Project Management:
The instructions below are for setting up a GitHub organization for your team.
You can create your GitHub account after receiving your team ID. Here are the instructions (please follow the organization/repo name format closely because we use scripts to download your code. If the names are not as expected, our scripts will not work):
CS2113-AY1819S1-TEAM_ID. e.g. CS2113-AY1819S1-W12-1developers to your organization.Only one team member:
main. This repo is to be used as the repo for your project.All team members:
main repo (created above) to your personal GitHub account.Note that some of our download scripts depend on the following folder paths. Please do not alter those paths in your project.
/src/main/src/test/docsWe use various tools to analyze your code. For us to be able to identify your commits, you should use the GitHub username as your Git username as well. If there is a mismatch, or if you use multiple user names for Git, our tools might miss some of your work and as a result you might not get credit for some of your work.
In each Computer you use for coding, after installing Git, you should set the Git username as follows.
git config --global user.name YOUR_GITHUB_USERNAMEgit config --global user.name JohnDoeMore info about setting Git username is here.
Documentation:
Recommended procedure for updating docs:
master branch to [addressbook-level4] (or [addressbook-level3])
master branch. PR name: [Team ID] Product Name e.g., [W12-2] Contact List Pro. In the PR description
Project Management → Revision Control →
In the forking workflow, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo create pull requests from their fork to the main repo.
To illustrate how the workflow goes, let’s assume Jean wants to fix a bug in the code. Here are the steps:
Update the following pages in your project repo:
doc/images/githbub_username_in_lower_case.png e.g. docs/images/akshay.png.The purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly -- somewhat similar to a passport photo. Some examples can be seen in the
'Teaching team' page. Given below are some examples of good and bad profile photos.
If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.
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.
Model, UI, Storage, etc. If you are in charge of a component, you are expected to know that component well,
and review changes done to that component in v1.3-v1.4.Please make sure 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.
README.adoc page: Update it to match your project.
docs/images/Ui.png so that it can be downloaded by our scripts.README.adoc file (which doubles as the landing page of your project website) is written to read like the introduction to an SE learning/teaching resource. You should restructure this page to look like the home page of a real product (not a school project) targeting real users e.g. remove references to addressbook-level3, Learning Outcomes etc. mention target users, add a marketing blurb etc. On a related note, also remove Learning Outcomes link and related pages.https://github.com/se-edu/User Guide: Start moving the content from your User Guide (draft created in previous weeks) into the User Guide page in your repository.
Developer Guide: Similar to the User Guide, start moving the content from your Developer Guide (draft created in previous weeks) into the Developer Guide page in your team repository.
Product:
Each member can attempt to do a
Objective: To familiarize yourself with at least one component the code.
Description: Divide the
Submission: Create PRs from your own fork to your team repo. Get it merged by following your team's workflow.
Before you start coding, please read
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 using 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.adoc (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//@@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 : (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 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.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your
PPP. Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section
is written by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else
(e.g. Start of Extract [from: User Guide] written by Jane Doe). Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
Overview: Update UG and DG in the repo, update project plan in repo, attempt to do global-impact changes to the code base.
v1.1 Summary of Milestone
| Milestone | Minimum acceptable performance to consider as 'reached' |
|---|---|
| Team org/repo set up | as stated |
| Project plan formalized | as stated |
| Have done some enhancement to the code | at least attempted to enhance the code of a component, even if you did not fully succeed |
| All project documents updated as required | updated docs are merged to the master branch |
Reminder: Reaching individual and team milestones are considered for
A. Process:
Evaluates: How well you did in project management related aspects of the project, as an individual and as a team
Based on: Supervisor observations of project milestones and GitHub data.
Milestones need to be reached the midnight before of the tutorial for it to be counted as achieved. To get a good grade this aspect, achieve recommended weekly progress in at least 6/10 weeks.
Other criteria:
B. Team-based tasks:
Evaluates: How much you contributed to common team-based tasks
Based on: peer evaluations and tutor observations
Relevant: [
Here is a non-exhaustive list of team-tasks:
Fix any errors in org/repo set up (e.g. wrong repo name).
When all changes intended for v1.1 is merged to the master branch, use git tag feature to tag the current version as v1.1
Start tracking your project schedule using GitHub issue tracker and milestones. More instructions coming soon.
Update User Guide, Developer Guide, README, and About Us pages as described earlier.
Submission: merge your changes to the master branch of your repo.
Overview: Adjust project schedule/rigor as needed, complete repo set up, start proper milestone management.
Project Management:
💡 You are free to adjust process rigor and project plan at any future time in the project, starting from v1.2. If you are not sure if a certain adjustment is allowed, you can check with the teaching team first.
Relevant: [
There is no explicit penalty for switching to a lower level AB. All projects are evaluated based on the same yardstick irrespective of on which AB it is based. As an AB is given to you as a 'free' head-start, a lower level AB gives
you a shorter head-start, which means your final product is likely to be less functional than those from teams using AB-4 unless you progress faster than them. Nevertheless, you should switch to AB2/3 if you feel you can learn
more from the project that way, as our goal is to maximize learning, not features.
If your team wants to stay with AB-4 but you want to switch to a lower level AB, let the us know so that we can work something out for you.
If you have opted to use AB-2 or AB-3 instead of AB-4 as the basis of your product, please note the following points:
Overview: Set up project repo, start moving UG and DG to the repo, attempt to do local-impact changes to the code base.
Project Management:
The instructions below are for setting up a GitHub organization for your team.
You can create your GitHub account after receiving your team ID. Here are the instructions (please follow the organization/repo name format closely because we use scripts to download your code. If the names are not as expected, our scripts will not work):
CS2113-AY1819S1-TEAM_ID. e.g. CS2113-AY1819S1-W12-1developers to your organization.Only one team member:
main. This repo is to be used as the repo for your project.All team members:
main repo (created above) to your personal GitHub account.Note that some of our download scripts depend on the following folder paths. Please do not alter those paths in your project.
/src/main/src/test/docsWe use various tools to analyze your code. For us to be able to identify your commits, you should use the GitHub username as your Git username as well. If there is a mismatch, or if you use multiple user names for Git, our tools might miss some of your work and as a result you might not get credit for some of your work.
In each Computer you use for coding, after installing Git, you should set the Git username as follows.
git config --global user.name YOUR_GITHUB_USERNAMEgit config --global user.name JohnDoeMore info about setting Git username is here.
Documentation:
Recommended procedure for updating docs:
master branch to [addressbook-level4] (or [addressbook-level3])
master branch. PR name: [Team ID] Product Name e.g., [W12-2] Contact List Pro. In the PR description
Project Management → Revision Control →
In the forking workflow, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo create pull requests from their fork to the main repo.
To illustrate how the workflow goes, let’s assume Jean wants to fix a bug in the code. Here are the steps:
Update the following pages in your project repo:
doc/images/githbub_username_in_lower_case.png e.g. docs/images/akshay.png.The purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly -- somewhat similar to a passport photo. Some examples can
be seen in the 'Teaching team' page. Given below are some examples of good and bad profile photos.
If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.
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.
Model, UI, Storage, etc. If you are in charge of a component, you are expected to know that
component well, and review changes done to that component in v1.3-v1.4.Please make sure 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.
README.adoc page: Update it to match your project.
docs/images/Ui.png so that it can be downloaded by our scripts.README.adoc file (which doubles as the landing page of your project website) is written to read like the introduction to an SE learning/teaching resource. You should restructure this page to look like the home page of a real product (not a school project) targeting real users e.g. remove references to addressbook-level3, Learning Outcomes etc. mention target users, add a marketing blurb etc. On a related note, also
remove Learning Outcomes link and related pages.https://github.com/se-edu/User Guide: Start moving the content from your User Guide (draft created in previous weeks) into the User Guide page in your repository.
Developer Guide: Similar to the User Guide, start moving the content from your Developer Guide (draft created in previous weeks) into the Developer Guide page in your team repository.
Product:
Each member can attempt to do a
Objective: To familiarize yourself with at least one component the code.
Description: Divide the
Submission: Create PRs from your own fork to your team repo. Get it merged by following your team's workflow.
Before you start coding, please read
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 using 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.adoc (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//@@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 : (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 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.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines
in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user
guide in your PPP. Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If
any section is written by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written
by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe). Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
Complete the repo set up.
Adjust project rigor to suit your team's pace, as explained below. Note that you are free to do similar adjustments at any future time in the project.
Automated tests have benefits, but they can be a pain to write/maintain; GUI tests are especially hard to maintain because their behavior can sometimes depend on things such as the OS, resolution etc.
It is OK to get rid of some of the troublesome tests and rely more on manual testing instead. The less automated test coverage you have, the higher the risk of regressions; but it may be an acceptable trade-off under the circumstances
if tests are slowing you down too much.
There is no direct penalty for removing GUI tests.
Also note
Automated checks: You can also reduce the rigor of checkstyle checks to expedite PR processing.
Workflow: Though you are recommended to follow the forking workflow when evolving the product, you can switch to a simpler workflow if the forking workflow is slowing you down.
Adjust project plan if necessary, as explained below. Note that you are free to do similar adjustments at any future time in the project.
Set up the issue tracker as described in
Start proper milestone management
When you create a repo, you get an issue tracker for that repo automatically. Configure it as follows:
Issue type labels:
type.epic : A big feature which can be broken down into smaller stories e.g. searchtype.story : A user storytype.enhancement: An enhancement to an existing storytype.task : Something that needs to be done, but not a story, bug, or an epic. e.g. Move testing code into a new folder)type.bug : A bugStatus labels:
status.ongoing : The issue is currently being worked on. note: remove this label before closing an issue.
Priority labels:
priority.high : Must dopriority.medium : Nice to havepriority.low : Unlikely to doBug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Create following milestones : v1.0, v1.1, v1.2, v1.3, v1.4,
You may configure other project settings as you wish. e.g. more labels, more milestones
In general, use the issue tracker (Milestones, Issues, PRs, Tags, Releases, and Labels) for assigning, scheduling, and tracking all noteworthy project tasks, including user stories. Update the issue tracker regularly to reflect the current status of the project. You can also use GitHub's new Projects feature to manage the project, but keep it linked to the issue tracker as much as you can.
Record each of the user stories you plan to deliver as an issue in the issue tracker.
e.g. Title: As a user I can add a deadline
Description: ... so that I can keep track of my deadlines
Assign the type.* and priority.* labels to those issues.
When you start implementing a story, break it down to tasks. Define reasonable sized, standalone tasks. A task should be able to done by one person, in a few hours. e.g.
Write a descriptive title for the issue. e.g. Add support for the 'undo' command to the parser.
There is no need to break things into VERY small tasks. Keep them as big as possible, but they should be no bigger than what you are going to assign a single person to do within a week. eg.,
Implementing parser : too big because it cannot be done by a single person in a week.Implementing parser support for adding of floating tasks : appropriate size.Do not track things taken for granted. e.g., push code to repo should not be a task to track. In the example given under the previous point, it is taken for granted that the owner will also (a) test the code and (b) push to the repo when it is ready. Those two need not be tracked as separate tasks.
Omit redundant details. In some cases, the summary/title is enough to describe the task. In that case, no need to repeat it in the description. There is no need for well-crafted and detailed descriptions for tasks.
A minimal description is enough. Similarly, labels such as priority can be omitted if you think they don't help you.
Assign tasks to team members using the assignees field. At any point, there should be some ongoing tasks and some pending tasks against each team member.
Optionally, you can use status.ongoing label to indicate issues currently ongoing.
Use GitHub milestones to indicate which issues are to be handled for which milestone by assigning issues to suitable milestones.
Set the deadlines for milestones (in GitHub). Your internal milestones can be set earlier than the deadlines we have set, to give you a buffer.
Note that you can change the milestone plan along the way as necessary.
Wrapping up a Milestone:
Here are the conditions to satisfy for a milestone to be considered properly wrapped up:
A working product tagged with the correct tag (e.g. v1.2) is pushed to the main repo.
All tests passing on Travis for the version tagged above.
Milestone updated to match the product i.e. all issues completed and PRs merged for the milestone should be assigned to the milestone.
Milestone closed. If there are incomplete issues or unmerged PRs in the milestone, move them to a future milestone.
Optionally, issues for the next milestone are assigned to team members (this is not compulsory to do before the tutorial, but we recommend you to do it soon after the tutorial).
Optionally, future milestones are revised based on what you experienced in the current milestone e.g. if you could not finish all issues assigned to the current milestone, it is a sign that you overestimated how much you can do in a week, which means you might want to reduce the issues assigned to future milestones to match that observation.
Doing a 'release' on GitHub is optional for v1.1 and v1.2 but compulsory from v1.3.
Product:
Overview: Move code towards v2.0 in small steps, start documenting design/implementation details in DG.
v1.2 Summary of Milestone
| Milestone | Minimum acceptable performance to consider as 'reached' |
|---|---|
| Contributed code to the product as described in mid-v1.2 progress guide | some code merged |
| Described implementation details in the Developer Guide | some text and some diagrams added to the developer guide (at least in a PR), comprising at least one page worth of content |
| v1.2 managed using GitHub features (issue tracker, milestones, etc.) | A new version git tagged v1.2 is in your repo.There is evidence of an attempt (even if not completely successful) to use GitHub features as described in |
In general, use the issue tracker (Milestones, Issues, PRs, Tags, Releases, and Labels) for assigning, scheduling, and tracking all noteworthy project tasks, including user stories. Update the issue tracker regularly to reflect the current status of the project. You can also use GitHub's new Projects feature to manage the project, but keep it linked to the issue tracker as much as you can.
Record each of the user stories you plan to deliver as an issue in the issue tracker.
e.g. Title: As a user I can add a deadline
Description: ... so that I can keep track of my deadlines
Assign the type.* and priority.* labels to those issues.
When you start implementing a story, break it down to tasks. Define reasonable sized, standalone tasks. A task should be able to done by one person, in a few hours. e.g.
Write a descriptive title for the issue. e.g. Add support for the 'undo' command to the parser.
There is no need to break things into VERY small tasks. Keep them as big as possible, but they should be no bigger than what you are going to assign a single person to do within a week. eg.,
Implementing parser : too big because it cannot be done by a single person in a week.Implementing parser support for adding of floating tasks : appropriate size.Do not track things taken for granted. e.g., push code to repo should not be a task to track. In the example given under the previous point, it is taken for granted that the owner will also (a) test the code and (b) push to the repo when it is ready. Those two need not be tracked as separate tasks.
Omit redundant details. In some cases, the summary/title is enough to describe the task. In that case, no need to repeat it in the description. There is no need for well-crafted and detailed descriptions for tasks.
A minimal description is enough. Similarly, labels such as priority can be omitted if you think they don't help you.
Assign tasks to team members using the assignees field. At any point, there should be some ongoing tasks and some pending tasks against each team member.
Optionally, you can use status.ongoing label to indicate issues currently ongoing.
Use GitHub milestones to indicate which issues are to be handled for which milestone by assigning issues to suitable milestones.
Set the deadlines for milestones (in GitHub). Your internal milestones can be set earlier than the deadlines we have set, to give you a buffer.
Note that you can change the milestone plan along the way as necessary.
Wrapping up a Milestone:
Here are the conditions to satisfy for a milestone to be considered properly wrapped up:
A working product tagged with the correct tag (e.g. v1.2) is pushed to the main repo.
All tests passing on Travis for the version tagged above.
Milestone updated to match the product i.e. all issues completed and PRs merged for the milestone should be assigned to the milestone.
Milestone closed. If there are incomplete issues or unmerged PRs in the milestone, move them to a future milestone.
Optionally, issues for the next milestone are assigned to team members (this is not compulsory to do before the tutorial, but we recommend you to do it soon after the tutorial).
Optionally, future milestones are revised based on what you experienced in the current milestone e.g. if you could not finish all issues assigned to the current milestone, it is a sign that you overestimated how much you can do in a week, which means you might want to reduce the issues assigned to future milestones to match that observation.
Doing a 'release' on GitHub is optional for v1.1 and v1.2 but compulsory from v1.3.
💡 We use a tool called Reposense to extract out code written by each member in your final project submission.
User Guide: Update as necessary.
Coming in v2.0 annotation from that feature. Also replace UI mock-ups with actual screenshots.Developer Guide:
Do an informal demo of the new feature during the tutorial. Each team member should demo their own work, using commit tagged as v1.2 in the master branch i.e. only features included in the current release should be demoed.
Overview: Continue to enhance features. Make code RepoSense-compatible. Try doing a proper release.
Project Management:
Ensure your code is
In previous semesters we asked students to annotate all their code using special @@author tags so that we can extract each student's code for grading. This semester, we are trying out a new tool called RepoSense that is
expected to reduce the need for such tagging, and also make it easier for you to see (and learn from) code written by others.
1. View the current status of code authorship data:
2. If the code does not match:
Here are the possible reasons for the code shown not to match the code you wrote:
In those cases,
config.json file to your repo (as specified by one of the two methods),
"authorNames": ["theMyth", "theLegend", "theGary"]config.json in the .gitignore file of your repo as /config.json so that it ignores the config.json produced by the app but not the _reposense/config.json.@@author annotations, please follow the guidelines below:@@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 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.
config.json file you added and/or the annotated code to your repo. We'll use that information the next time we
run RepoSense (we run it at least once a week).We recommend you ensure your code is RepoSense-compatible by v1.3
Product:
v1.2.1. Ensure that the jar file works as expected by doing some manual testing. Reason: You are required to do a proper product release for v1.3. Doing a trial at this point will help you iron out any problems in advance. It may take additional effort to get the jar working especially if you use third party libraries or additional assets such as images.Documentation:
Demo:
Overview: Release as a jar file, release updated user guide, peer-test released products, verify code authorship.
v1.3 Summary of Milestone
| Milestone | Minimum acceptable performance to consider as 'reached' |
|---|---|
| Contributed code to v1.3 | code merged |
| v1.3 jar file released properly on GitHub | as stated |
| v1.3 milestone properly wrapped up on GitHub | as stated |
| Documentation updated to match v1.3 | at least the User Guide and the README.adoc is updated |
Updated Instructions
We will depend on Reposense for identifying your code contribution. At the moment, you are NOT required to collate your code. However, the teaching team will monitor Reposense for another week and confirm via an announcement.
As before, move the product towards v2.0.
Submission: Push the code to GitHub.
v1.3 user guide should be updated to match the current version of the product. Reason: v1.3 will be subjected to a trial acceptance testing session
README page: Update to look like a real product (rather than a project for learning SE) if you haven't done so already. In particular,
Ui.png to match the current productUser Guide: This document will be used by acceptance testers. Update to match the current version. In particular,
Coming in v2.0.Developer Guide: As before, update if necessary.
AboutUs page: Update to reflect current state of roles and responsibilities.
Submission: Must be included in the version tagged v1.3.
See info in the panel below
Relevant: [
What: The v1.3 is subjected to a round of peer acceptance/system testing, also called the Practical Exam Round 1 (PE-1). This round of testing will be graded similar to the
When, where: 45 minute slot at the end of week 11 lecture, in the Lecture venue
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2:
nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough
details rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands
edit, undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students
to be have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given
below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You
can also reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility.
If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Grading: Taking part in the PE-1 is strongly encouraged as it can affect your grade in the following ways.
Objectives:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During the session:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP.
Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written
by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
After the session:
Overview: Tweak as per peer-testing results, draft Project Portfolio Page, practice product demo.
Project Management:
Relevant: [
In previous semesters we asked students to annotate all their code using special @@author tags so that we can extract each student's code for grading. This semester, we are trying out a new tool called RepoSense that is
expected to reduce the need for such tagging, and also make it easier for you to see (and learn from) code written by others.
1. View the current status of code authorship data:
2. If the code does not match:
Here are the possible reasons for the code shown not to match the code you wrote:
In those cases,
config.json file to your repo (as specified by one of the two methods),
"authorNames": ["theMyth", "theLegend", "theGary"]config.json in the .gitignore file of your repo as /config.json so that it ignores the config.json produced by the app but not the _reposense/config.json.@@author annotations, please follow the guidelines below:@@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 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.
config.json file you added and/or the annotated code to your repo. We'll use that information the next time we
run RepoSense (we run it at least once a week).We recommend you ensure your code is RepoSense-compatible by v1.3
Product:
Relevant: [
Ensure your code has at least some evidence of these (see here for more info)
Ensure there are 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.
Ensure SLAP is applied at a reasonable level. Long methods or deeply-nested code are symptoms of low-SLAP may be counted against your code quality.
Reduce 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.
In addition, try to apply as many of the
Can explain the importance of code quality
Always code as if the person who ends up maintaining your code will be a violent psychopath who knows where you live. -- Martin Golding
Can explain the importance of readability
Programs should be written and polished until they acquire publication quality. --Niklaus Wirth
Among various dimensions of code quality, such as run-time efficiency, security, and robustness, one of the most important is understandability. This is because in any non-trivial software project, code needs to be read, understood, and modified by other developers later on. Even if we do not intend to pass the code to someone else, code quality is still important because we all become 'strangers' to our own code someday.
The two code samples given below achieve the same functionality, but one is easier to read.
|
Bad |
|
Good |
|
Bad |
|
Good |
Can improve code quality using technique: avoid long methods
Be wary when a method is longer than the computer screen, and take corrective action when it goes beyond 30 LOC (lines of code). The bigger the haystack, the harder it is to find a needle.
Can improve code quality using technique: avoid deep nesting
If you need more than 3 levels of indentation, you're screwed anyway, and should fix your program. --Linux 1.3.53 CodingStyle
In particular, avoid arrowhead style code.
Example:
Can improve code quality using technique: avoid complicated expressions
Avoid complicated expressions, especially those having many negations and nested parentheses. If you must evaluate complicated expressions, have it done in steps (i.e. calculate some intermediate values first and use them to calculate the final value).
Example:
Bad
return ((length < MAX_LENGTH) || (previousSize != length)) && (typeCode == URGENT);
Good
boolean isWithinSizeLimit = length < MAX_LENGTH;
boolean isSameSize = previousSize != length;
boolean isValidCode = isWithinSizeLimit || isSameSize;
boolean isUrgent = typeCode == URGENT;
return isValidCode && isUrgent;
Example:
Bad
return ((length < MAX_LENGTH) or (previous_size != length)) and (type_code == URGENT)
Good
is_within_size_limit = length < MAX_LENGTH
is_same_size = previous_size != length
is_valid_code = is_within_size_limit or is_same_size
is_urgent = type_code == URGENT
return is_valid_code and is_urgent
The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague. -- Edsger Dijkstra
Can improve code quality using technique: avoid magic numbers
When the code has a number that does not explain the meaning of the number, we call that a magic number (as in “the number appears as if by magic”). Using a
Example:
|
Bad |
|
Good |
Note: Python does not have a way to make a variable a constant. However, you can use a normal variable with an ALL_CAPS name to simulate a constant.
|
Bad |
|
Good |
Similarly, we can have ‘magic’ values of other data types.
Bad
"Error 1432" // A magic string!
Can improve code quality using technique: make the code obvious
Make the code as explicit as possible, even if the language syntax allows them to be implicit. Here are some examples:
Java] Use explicit type conversion instead of implicit type conversion.Java, Python] Use parentheses/braces to show grouping even when they can be skipped.Java, Python] Use
SystemState and define an enumeration SystemState that has values 'STARTING',
'ENABLED', and 'DISABLED'.Can improve code quality using technique: structure code logically
Lay out the code so that it adheres to the logical structure. The code should read like a story. Just like we use section breaks, chapters and paragraphs to organize a story, use classes, methods, indentation and line spacing in your code to group related segments of the code. For example, you can use blank lines to group related statements together. Sometimes, the correctness of your code does not depend on the order in which you perform certain intermediary steps. Nevertheless, this order may affect the clarity of the story you are trying to tell. Choose the order that makes the story most readable.
Can improve code quality using technique: do not 'trip up' reader
Avoid things that would make the reader go ‘huh?’, such as,
Can improve code quality using technique: practice kissing
As the old adage goes, "keep it simple, stupid” (KISS). Do not try to write ‘clever’ code. For example, do not dismiss the brute-force yet simple solution in favor of a complicated one because of some ‘supposed benefits’ such as 'better reusability' unless you have a strong justification.
Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. --Brian W. Kernighan
Programs must be written for people to read, and only incidentally for machines to execute. --Abelson and Sussman
Can improve code quality using technique: avoid premature optimizations
Optimizing code prematurely has several drawbacks:
A popular saying in the industry is make it work, make it right, make it fast which means in most cases getting the code to perform correctly should take priority over optimizing it. If the code doesn't work correctly, it has no value on matter how fast/efficient it it.
Premature optimization is the root of all evil in programming. --Donald Knuth
Note that there are cases where optimizing takes priority over other things e.g. when writing code for resource-constrained environments. This guideline simply a caution that you should optimize only when it is really needed.
Can improve code quality using technique: SLAP hard
Avoid varying the level of
Example:
Bad
readData();
salary = basic*rise+1000;
tax = (taxable?salary*0.07:0);
displayResult();
Good
readData();
processData();
displayResult();
Design → Design Fundamentals → Abstraction →
Abstraction is a technique for dealing with complexity. It works by establishing a level of complexity (or an aspect) we are interested in, and suppressing the more complex details below that level (or irrelevant to that aspect).
Most programs are written to solve complex problems involving large amounts of intricate details. It is impossible to deal with all these details at the same time. The guiding principle of abstraction stipulates that we capture only details that are relevant to the current perspective or the task at hand.
Ignoring lower level data items and thinking in terms of bigger entities is called data abstraction.
Within a certain software component, we might deal with a user data type, while ignoring the details contained in the user data item such as name, and date of birth. These details have been ‘abstracted away’ as they do not affect the task of that software component.
Control abstraction abstracts away details of the actual control flow to focus on tasks at a simplified level.
print(“Hello”) is an abstraction of the actual output mechanism within the computer.
Abstraction can be applied repeatedly to obtain progressively higher levels of abstractions.
An example of different levels of data abstraction: a File is a data item that is at a higher level than an array and an array is at a higher level
than a bit.
An example of different levels of control abstraction: execute(Game) is at a higher level than print(Char) which is at a higher than
an Assembly language instruction MOV.
Can improve code quality using technique: make the happy path prominent
The happy path (i.e. the execution path taken when everything goes well) should be clear and prominent in your code. Restructure the code to make the happy path unindented as much as possible. It is the ‘unusual’ cases that should be indented. Someone reading the code should not get distracted by alternative paths taken when error conditions happen. One technique that could help in this regard is the use of guard clauses.
Example:
Bad
if (!isUnusualCase) { //detecting an unusual condition
if (!isErrorCase) {
start(); //main path
process();
cleanup();
exit();
} else {
handleError();
}
} else {
handleUnusualCase(); //handling that unusual condition
}
In the code above,
Good
if (isUnusualCase) { //Guard Clause
handleUnusualCase();
return;
}
if (isErrorCase) { //Guard Clause
handleError();
return;
}
start();
process();
cleanup();
exit();
In contrast, the above code
Can explain the need for following a standard
One essential way to improve code quality is to follow a consistent style. That is why software engineers follow a strict coding standard (aka style guide).
The aim of a coding standard is to make the entire code base look like it was written by one person. A coding standard is usually specific to a programming language and specifies guidelines such as the location of opening and closing braces, indentation styles and naming styles (e.g. whether to use Hungarian style, Pascal casing, Camel casing, etc.). It is important that the whole team/company use the same coding standard and that standard is not generally inconsistent with typical industry practices. If a company's coding standards is very different from what is used typically in the industry, new recruits will take longer to get used to the company's coding style.
💡 IDEs can help to enforce some parts of a coding standard e.g. indentation rules.
What is the recommended approach regarding coding standards?
c
What is the aim of using a coding standard? How does it help?
Can follow simple mechanical style rules
Learn basic guidelines of the Java coding standard (by OSS-Generic)
Sample coding standard: PEP 8 Python Style Guide -- by Python.org
Consider the code given below:
import java.util.*;
public class Task {
public static final String descriptionPrefix = "description: ";
private String description;
private boolean important;
List<String> pastDescription = new ArrayList<>(); // a list of past descriptions
public Task(String d) {
this.description = d;
if (!d.isEmpty())
this.important = true;
}
public String getAsXML() { return "<task>"+description+"</task>"; }
/**
* Print the description as a string.
*/
public void printingDescription(){ System.out.println(this); }
@Override
public String toString() { return descriptionPrefix + description; }
}
In what ways the code violate the basic guidelines (i.e., those marked with one ⭐️) of the OSS-Generic Java Coding Standard given here?
Here are three:
descriptionPrefix is a constant and should be named DESCRIPTION_PREFIXprintingDescription() should be named as printDescription()important should be named to sound boolean e.g., isImportantThere are many more.
Can follow intermediate style rules
Go through the provided Java coding standard and learn the intermediate style rules.
According to the given Java coding standard, which one of these is not a good name?
b
Explanation: checkWeight is an action. Naming variables as actions makes the code harder to follow. isWeightValid may be a better name.
Repeat the exercise in the panel below but also find violations of intermediate level guidelines.
Consider the code given below:
import java.util.*;
public class Task {
public static final String descriptionPrefix = "description: ";
private String description;
private boolean important;
List<String> pastDescription = new ArrayList<>(); // a list of past descriptions
public Task(String d) {
this.description = d;
if (!d.isEmpty())
this.important = true;
}
public String getAsXML() { return "<task>"+description+"</task>"; }
/**
* Print the description as a string.
*/
public void printingDescription(){ System.out.println(this); }
@Override
public String toString() { return descriptionPrefix + description; }
}
In what ways the code violate the basic guidelines (i.e., those marked with one ⭐️) of the OSS-Generic Java Coding Standard given here?
Here are three:
descriptionPrefix is a constant and should be named DESCRIPTION_PREFIXprintingDescription() should be named as printDescription()important should be named to sound boolean e.g., isImportantThere are many more.
Here's one you are more likely to miss:
* Print the description as a string. → * Prints the description as a string.There are more.
Can explain the need for good names in code
Proper naming improves the readability. It also reduces bugs caused by ambiguities regarding the intent of a variable or a method.
There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
Can improve code quality using technique: use nouns for things and verbs for actions
Use nouns for classes/variables and verbs for methods/functions.
Examples:
| Name for a | Bad | Good |
|---|---|---|
| Class | CheckLimit |
LimitChecker |
| method | result() |
calculate() |
Distinguish clearly between single-valued and multivalued variables.
Examples:
Good
Person student;
ArrayList<Person> students;
Good
student = Person('Jim')
students = [Person('Jim'), Person('Alice')]
Can improve code quality using technique: use standard words
Use correct spelling in names. Avoid 'texting-style' spelling. Avoid foreign language words, slang, and names that are only meaningful within specific contexts/times e.g. terms from private jokes, a TV show currently popular in your country
Can improve code quality using technique: use name to explain
A name is not just for differentiation; it should explain the named entity to the reader accurately and at a sufficient level of detail.
Examples:
| Bad | Good |
|---|---|
processInput() (what 'process'?) |
removeWhiteSpaceFromInput() |
flag |
isValidInput |
temp |
If the name has multiple words, they should be in a sensible order.
Examples:
| Bad | Good |
|---|---|
bySizeOrder() |
orderBySize() |
Imagine going to the doctor's and saying "My eye1 is swollen"! Don’t use numbers or case to distinguish names.
Examples:
| Bad | Bad | Good |
|---|---|---|
value1, value2 |
value, Value |
originalValue, finalValue |
Can improve code quality using technique: not too long, not too short
While it is preferable not to have lengthy names, names that are 'too short' are even worse. If you must abbreviate or use acronyms, do it consistently. Explain their full meaning at an obvious location.
Can improve code quality using technique: avoid misleading names
Related things should be named similarly, while unrelated things should NOT.
Example: Consider these variables
colorBlack : hex value for color blackcolorWhite : hex value for color whitecolorBlue : number of times blue is usedhexForRed : : hex value for color redThis is misleading because colorBlue is named similar to colorWhite and colorBlack but has a different purpose while hexForRed is named differently but
has very similar purpose to the first two variables. The following is better:
hexForBlack hexForWhite hexForRedblueColorCountAvoid misleading or ambiguous names (e.g. those with multiple meanings), similar sounding names, hard-to-pronounce ones (e.g. avoid ambiguities like "is that a lowercase L, capital I or number 1?", or "is that number 0 or letter O?"), almost similar names.
Examples:
| Bad | Good | Reason |
|---|---|---|
phase0 |
phaseZero |
Is that zero or letter O? |
rwrLgtDirn |
rowerLegitDirection |
Hard to pronounce |
right left wrong |
rightDirection leftDirection wrongResponse |
right is for 'correct' or 'opposite of 'left'? |
redBooks readBooks |
redColorBooks booksRead |
red and read (past tense) sounds the same |
FiletMignon |
egg |
If the requirement is just a name of a food, egg is a much easier to type/say choice than FiletMignon |
Can explain the need for avoiding error-prone shortcuts
It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Some such coding practices are common sources of bugs. Know them and avoid them.
Can improve code quality using technique: use the default branch
Always include a default branch in case statements.
Furthermore, use it for the intended default action and not just to execute the last option. If there is no default action, you can use the 'default' branch to detect errors (i.e. if execution reached the
default branch, throw an exception). This also applies to the final else of an if-else construct. That is, the final else should mean 'everything else',
and not the final option. Do not use else when an if condition can be explicitly specified, unless there is absolutely no other possibility.
Bad
if (red) print "red";
else print "blue";
Good
if (red) print "red";
else if (blue) print "blue";
else error("incorrect input");
Can improve code quality using technique: don't recycle variables or parameters
Bad
double computeRectangleArea(double length, double width) {
length = length * width;
return length;
}
Good
double computeRectangleArea(double length, double width) {
double area;
area = length * width;
return area;
}
Can improve code quality using technique: avoid empty catch blocks
Never write an empty catch statement. At least give a comment to explain why the catch block is left empty.
Can improve code quality using technique: delete dead code
We all feel reluctant to delete code we have painstakingly written, even if we have no use for that code any more ("I spent a lot of time writing that code; what if we need it again?"). Consider all code as baggage you have to carry; get rid of unused code the moment it becomes redundant. If you need that code again, simply recover it from the revision control tool you are using. Deleting code you wrote previously is a sign that you are improving.
Can improve code quality using technique: minimise scope of variables
Minimize global variables. Global variables may be the most convenient way to pass information around, but they do create implicit links between code segments that use the global variable. Avoid them as much as possible.
Define variables in the least possible scope. For example, if the variable is used only within the if block of the conditional statement, it should be declared inside that if block.
The most powerful technique for minimizing the scope of a local variable is to declare it where it is first used. -- Effective Java, by Joshua Bloch
Resources:
Can improve code quality using technique: minimise code duplication
Code duplication, especially when you copy-paste-modify code, often indicates a poor quality implementation. While it may not be possible to have zero duplication, always think twice before duplicating code; most often there is a better alternative.
This guideline is closely related to the
Supplmentary → Principles →
DRY (Don't Repeat Yourself) Principle: Every piece of knowledge must have a single, unambiguous, authoritative representation within a system The Pragmatic Programmer, by Andy Hunt and Dave Thomas
This principle guards against duplication of information.
The functionality implemented twice is a violation of the DRY principle even if the two implementations are different.
The value a system-wide timeout being defined in multiple places is a violation of DRY.
Can explain the need for commenting minimally but sufficiently
Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer. --Steve McConnell, Author of Clean Code
Some think commenting heavily increases the 'code quality'. This is not so. Avoid writing comments to explain bad code. Improve the code to make it self-explanatory.
Can improve code quality using technique: do not repeat the obvious
If the code is self-explanatory, refrain from repeating the description in a comment just for the sake of 'good documentation'.
Bad
// increment x
x++;
//trim the input
trimInput();
Can improve code quality using technique: write to the reader
Do not write comments as if they are private notes to self. Instead, write them well enough to be understood by another programmer. One type of comments that is almost always useful is the header comment that you write for a class or an operation to explain its purpose.
Examples:
Bad Reason: this comment will only make sense to the person who wrote it
// a quick trim function used to fix bug I detected overnight
void trimInput(){
....
}
Good
/** Trims the input of leading and trailing spaces */
void trimInput(){
....
}
Bad Reason: this comment will only make sense to the person who wrote it
# a quick trim function used to fix bug I detected overnight
def trim_input():
...
Good
def trim_input():
"""Trim the input of leading and trailing spaces"""
...
Can improve code quality using technique: explain what and why, not how
Comments should explain what and why aspect of the code, rather than the how aspect.
👍 What : The specification of what the code supposed to do. The reader can compare such comments to the implementation to verify if the implementation is correct
Example: This method is possibly buggy because the implementation does not seem to match the comment. In this case the comment could help the reader to detect the bug.
/** Removes all spaces from the {@code input} */
void compact(String input){
input.trim();
}
👍 Why : The rationale for the current implementation.
Example: Without this comment, the reader will not know the reason for calling this method.
// Remove spaces to comply with IE23.5 formatting rules
compact(input);
👎 How : The explanation for how the code works. This should already be apparent from the code, if the code is self-explanatory. Adding comments to explain the same thing is redundant.
Example:
Bad Reason: Comment explains how the code works.
// return true if both left end and right end are correct or the size has not incremented
return (left && right) || (input.size() == size);
Good Reason: Code refactored to be self-explanatory. Comment no longer needed.
boolean isSameSize = (input.size() == size) ;
return (isLeftEndCorrect && isRightEndCorrect) || isSameSize;
null
Documentation:
Update documentation to match the product.
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. Creating a PPP takes a significant effort; it is too risky to leave it to the last week of the project.
Relevant: [
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP. Follow
the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written
by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
Demo:
Duration: Strictly (teamSize x 3.5) + 1 minutes e.g. 19 minutes for a 5-person team. Exceeding this limit will be penalized. The extra minute is for the first speaker to give
an overview of the product.
Target audience: Assume you are giving a demo to a higher-level manager of your company, to brief him/her on the current capabilities of the product. This is the first time they are seeing the new product you developed but they are familiar with the AddressBook-level4 (AB4) product.
Scope:
Structure:
Optimizing the time:
Jim get’s a call from boss. "Ring ring", "hello", "oh hi Jim, can we postpone the meeting?" "Sure". Jim hang up and curses the boss under his breath. Now he starts typing ..etc. [do this] If Jim needs to postpone the meeting, he can type … It’s not that dramatization is bad or we don’t like it. We simply don’t have enough time for it.Overview: Final tweaks to docs/product, release product, demo product, evaluate peer projects.
Summary of submissions:
| Team/Individual Item | Name format | Upload to |
|---|---|---|
| Source code | tag as v1.4 |
GitHub |
| Jar file | [team][product name].jare.g. [T09-1][ContactsPlus].jar |
IVLE |
| User Guide | [TEAM_ID][Product Name]UserGuide.pdfe.g.[T09-1][Contacts Plus]UserGuide.pdf |
IVLE |
| Developer Guide | [TEAM_ID][Product Name]DeveloperGuide.pdfe.g. [T09-1][Contacts Plus]DeveloperGuide.pdf |
IVLE |
| Product Website | README page, Ui.png, AboutUs page |
github.io |
| Project Portfolio Page | [TEAM_ID][Your Name]Portfolio.pdfe.g.[T09-1][John Doe]Portfolio.pdf html version of PPP page on the product website |
IVLE github.io |
Deadline for all v1.4 submissions is Week 13 Monday 23.59 unless stated otherwise.
Grading:
Described in [Admin: Project: Assessment]
Relevant: [
Submission: See summary of submissions above
Relevant: [
Submission: Push the code to GitHub and tag with the version number. Source code (please ensure the code reported by RepoSense as yours is correct; any updates to RepoSense config files or @@author annotations after the deadline will be considered a later submission). Note that the quality of the code attributed to you accounts for a significant component of your final score, graded individually.
Relevant: [
Coming in v2.0
Submission: Convert the pdf (AB4 dev guide has some instructions on converting project docs to pdf) and upload to IVLE. See summary of submissions above for the file name format.
Relevant: [
Submission: Similar to UG
Relevant: [
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP. Follow
the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written
by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
Submission: Similar to UG
Relevant: [
Ui.png matches the current productThe purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly -- somewhat similar to a passport photo. Some examples can be seen in the
'Teaching team' page. Given below are some examples of good and bad profile photos.
If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.
Submission: Push the code to GitHub. Ensure the website is auto-published.
Relevant: [
Duration: Strictly (teamSize x 3.5) + 1 minutes e.g. 19 minutes for a 5-person team. Exceeding this limit will be penalized. The extra minute is for the first speaker to
give an overview of the product.
Target audience: Assume you are giving a demo to a higher-level manager of your company, to brief him/her on the current capabilities of the product. This is the first time they are seeing the new product you developed but they are familiar with the AddressBook-level4 (AB4) product.
Scope:
Structure:
Optimizing the time:
Jim get’s a call from boss. "Ring ring", "hello", "oh hi Jim, can we postpone the meeting?" "Sure". Jim hang up and curses the boss under his breath. Now he starts typing ..etc. [do this] If Jim needs to postpone the meeting, he can type … It’s not that dramatization is bad or we don’t like it. We simply don’t have enough time for it.
Relevant: [
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough details
rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands edit,
undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students
to be have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You can
also reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility.
If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Time/venue: week 13 lecture slot
Here is a list of main deliverables of the project; their details are given in the subsequent sections.
Coming in v2.0Ui.png matches the current productThe purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly -- somewhat similar to a passport photo. Some examples can be seen in the 'Teaching team' page. Given below are some examples of good and bad profile photos.
If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP. Follow the
example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written by someone
else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
Duration: Strictly (teamSize x 3.5) + 1 minutes e.g. 19 minutes for a 5-person team. Exceeding this limit will be penalized. The extra minute is for the first speaker to give an
overview of the product.
Target audience: Assume you are giving a demo to a higher-level manager of your company, to brief him/her on the current capabilities of the product. This is the first time they are seeing the new product you developed but they are familiar with the AddressBook-level4 (AB4) product.
Scope:
Structure:
Optimizing the time:
Jim get’s a call from boss. "Ring ring", "hello", "oh hi Jim, can we postpone the meeting?" "Sure". Jim hang up and curses the boss under his breath. Now he starts typing ..etc. [do this] If Jim needs to postpone the meeting, he can type … It’s not that dramatization is bad or we don’t like it. We simply don’t have enough time for it.What: The v1.3 is subjected to a round of peer acceptance/system testing, also called the Practical Exam Round 1 (PE-1). This round of testing will be graded similar to the
When, where: 45 minute slot at the end of week 11 lecture, in the Lecture venue
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough details
rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands edit,
undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students to be
have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You can also
reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility. If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Grading: Taking part in the PE-1 is strongly encouraged as it can affect your grade in the following ways.
Objectives:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During the session:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP. Follow
the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written
by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
After the session:
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough details rather
than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands edit,
undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students to be
have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You can also reject
bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility. If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
There is no explicit penalty for switching to a lower level AB. All projects are evaluated based on the same yardstick irrespective of on which AB it is based. As an AB is given to you as a 'free' head-start, a lower level AB gives you a shorter head-start, which means your final product is likely to be less functional than those from teams using AB-4 unless you progress faster than them. Nevertheless, you should switch to AB2/3 if you feel you can learn more from the project that way, as our goal is to maximize learning, not features.
If your team wants to stay with AB-4 but you want to switch to a lower level AB, let the us know so that we can work something out for you.
If you have opted to use AB-2 or AB-3 instead of AB-4 as the basis of your product, please note the following points:
Overview: Set up project repo, start moving UG and DG to the repo, attempt to do local-impact changes to the code base.
Project Management:
The instructions below are for setting up a GitHub organization for your team.
You can create your GitHub account after receiving your team ID. Here are the instructions (please follow the organization/repo name format closely because we use scripts to download your code. If the names are not as expected, our scripts will not work):
CS2113-AY1819S1-TEAM_ID. e.g. CS2113-AY1819S1-W12-1developers to your organization.Only one team member:
main. This repo is to be used as the repo for your project.All team members:
main repo (created above) to your personal GitHub account.Note that some of our download scripts depend on the following folder paths. Please do not alter those paths in your project.
/src/main/src/test/docsWe use various tools to analyze your code. For us to be able to identify your commits, you should use the GitHub username as your Git username as well. If there is a mismatch, or if you use multiple user names for Git, our tools might miss some of your work and as a result you might not get credit for some of your work.
In each Computer you use for coding, after installing Git, you should set the Git username as follows.
git config --global user.name YOUR_GITHUB_USERNAMEgit config --global user.name JohnDoeMore info about setting Git username is here.
Documentation:
Recommended procedure for updating docs:
master branch to [addressbook-level4] (or [addressbook-level3])
master branch. PR name: [Team ID] Product Name e.g., [W12-2] Contact List Pro. In the PR description
Project Management → Revision Control →
In the forking workflow, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo create pull requests from their fork to the main repo.
To illustrate how the workflow goes, let’s assume Jean wants to fix a bug in the code. Here are the steps:
Update the following pages in your project repo:
doc/images/githbub_username_in_lower_case.png e.g. docs/images/akshay.png.The purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly -- somewhat similar to a passport photo. Some examples can be seen in the
'Teaching team' page. Given below are some examples of good and bad profile photos.
If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.
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.
Model, UI, Storage, etc. If you are in charge of a component, you are expected to know that component well,
and review changes done to that component in v1.3-v1.4.Please make sure 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.
README.adoc page: Update it to match your project.
docs/images/Ui.png so that it can be downloaded by our scripts.README.adoc file (which doubles as the landing page of your project website) is written to read like the introduction to an SE learning/teaching resource. You should restructure this page to look like the home page of a real product (not a school project) targeting real users e.g. remove references to addressbook-level3, Learning Outcomes etc. mention target users, add a marketing blurb etc. On a related note, also remove Learning Outcomes link and related pages.https://github.com/se-edu/User Guide: Start moving the content from your User Guide (draft created in previous weeks) into the User Guide page in your repository.
Developer Guide: Similar to the User Guide, start moving the content from your Developer Guide (draft created in previous weeks) into the Developer Guide page in your team repository.
Product:
Each member can attempt to do a
Objective: To familiarize yourself with at least one component the code.
Description: Divide the
Submission: Create PRs from your own fork to your team repo. Get it merged by following your team's workflow.
Before you start coding, please read
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 using 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.adoc (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//@@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 : (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 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.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your
PPP. Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section
is written by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else
(e.g. Start of Extract [from: User Guide] written by Jane Doe). Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
Note that project grading is not competitive (not bell curved). CS2113T projects will be assessed separately from CS2113 projects. This is to account for the perceived difference in workload. Given below is the marking scheme.
Total: 50 marks ( 40 individual marks + 10 team marks)
Evaluates: How well do your features fit together to form a cohesive product (not how many features or how big the features are)?
Based on: user guide and the product demo. The quality of the demo will be factored in as well.
❗️ Feature that fits well with the other features will earn more marks.
Evaluates:
A. Code quality/quantity:
How good your implementation is, in terms of the quality and the quantity of the code you have written yourself.
Based on: an inspection of the collated code (obtained from Reposense).
Ensure your code has at least some evidence of these (see here for more info)
Ensure there are 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.
Ensure SLAP is applied at a reasonable level. Long methods or deeply-nested code are symptoms of low-SLAP may be counted against your code quality.
Reduce 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.
In addition, try to apply as many of the
Can explain the importance of code quality
Always code as if the person who ends up maintaining your code will be a violent psychopath who knows where you live. -- Martin Golding
Can explain the importance of readability
Programs should be written and polished until they acquire publication quality. --Niklaus Wirth
Among various dimensions of code quality, such as run-time efficiency, security, and robustness, one of the most important is understandability. This is because in any non-trivial software project, code needs to be read, understood, and modified by other developers later on. Even if we do not intend to pass the code to someone else, code quality is still important because we all become 'strangers' to our own code someday.
The two code samples given below achieve the same functionality, but one is easier to read.
|
Bad |
|
Good |
|
Bad |
|
Good |
Can improve code quality using technique: avoid long methods
Be wary when a method is longer than the computer screen, and take corrective action when it goes beyond 30 LOC (lines of code). The bigger the haystack, the harder it is to find a needle.
Can improve code quality using technique: avoid deep nesting
If you need more than 3 levels of indentation, you're screwed anyway, and should fix your program. --Linux 1.3.53 CodingStyle
In particular, avoid arrowhead style code.
Example:
Can improve code quality using technique: avoid complicated expressions
Avoid complicated expressions, especially those having many negations and nested parentheses. If you must evaluate complicated expressions, have it done in steps (i.e. calculate some intermediate values first and use them to calculate the final value).
Example:
Bad
return ((length < MAX_LENGTH) || (previousSize != length)) && (typeCode == URGENT);
Good
boolean isWithinSizeLimit = length < MAX_LENGTH;
boolean isSameSize = previousSize != length;
boolean isValidCode = isWithinSizeLimit || isSameSize;
boolean isUrgent = typeCode == URGENT;
return isValidCode && isUrgent;
Example:
Bad
return ((length < MAX_LENGTH) or (previous_size != length)) and (type_code == URGENT)
Good
is_within_size_limit = length < MAX_LENGTH
is_same_size = previous_size != length
is_valid_code = is_within_size_limit or is_same_size
is_urgent = type_code == URGENT
return is_valid_code and is_urgent
The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague. -- Edsger Dijkstra
Can improve code quality using technique: avoid magic numbers
When the code has a number that does not explain the meaning of the number, we call that a magic number (as in “the number appears as if by magic”). Using a
Example:
|
Bad |
|
Good |
Note: Python does not have a way to make a variable a constant. However, you can use a normal variable with an ALL_CAPS name to simulate a constant.
|
Bad |
|
Good |
Similarly, we can have ‘magic’ values of other data types.
Bad
"Error 1432" // A magic string!
Can improve code quality using technique: make the code obvious
Make the code as explicit as possible, even if the language syntax allows them to be implicit. Here are some examples:
Java] Use explicit type conversion instead of implicit type conversion.Java, Python] Use parentheses/braces to show grouping even when they can be skipped.Java, Python] Use
SystemState and define an enumeration SystemState that has values 'STARTING', 'ENABLED',
and 'DISABLED'.Can improve code quality using technique: structure code logically
Lay out the code so that it adheres to the logical structure. The code should read like a story. Just like we use section breaks, chapters and paragraphs to organize a story, use classes, methods, indentation and line spacing in your code to group related segments of the code. For example, you can use blank lines to group related statements together. Sometimes, the correctness of your code does not depend on the order in which you perform certain intermediary steps. Nevertheless, this order may affect the clarity of the story you are trying to tell. Choose the order that makes the story most readable.
Can improve code quality using technique: do not 'trip up' reader
Avoid things that would make the reader go ‘huh?’, such as,
Can improve code quality using technique: practice kissing
As the old adage goes, "keep it simple, stupid” (KISS). Do not try to write ‘clever’ code. For example, do not dismiss the brute-force yet simple solution in favor of a complicated one because of some ‘supposed benefits’ such as 'better reusability' unless you have a strong justification.
Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. --Brian W. Kernighan
Programs must be written for people to read, and only incidentally for machines to execute. --Abelson and Sussman
Can improve code quality using technique: avoid premature optimizations
Optimizing code prematurely has several drawbacks:
A popular saying in the industry is make it work, make it right, make it fast which means in most cases getting the code to perform correctly should take priority over optimizing it. If the code doesn't work correctly, it has no value on matter how fast/efficient it it.
Premature optimization is the root of all evil in programming. --Donald Knuth
Note that there are cases where optimizing takes priority over other things e.g. when writing code for resource-constrained environments. This guideline simply a caution that you should optimize only when it is really needed.
Can improve code quality using technique: SLAP hard
Avoid varying the level of
Example:
Bad
readData();
salary = basic*rise+1000;
tax = (taxable?salary*0.07:0);
displayResult();
Good
readData();
processData();
displayResult();
Design → Design Fundamentals → Abstraction →
Abstraction is a technique for dealing with complexity. It works by establishing a level of complexity (or an aspect) we are interested in, and suppressing the more complex details below that level (or irrelevant to that aspect).
Most programs are written to solve complex problems involving large amounts of intricate details. It is impossible to deal with all these details at the same time. The guiding principle of abstraction stipulates that we capture only details that are relevant to the current perspective or the task at hand.
Ignoring lower level data items and thinking in terms of bigger entities is called data abstraction.
Within a certain software component, we might deal with a user data type, while ignoring the details contained in the user data item such as name, and date of birth. These details have been ‘abstracted away’ as they do not affect the task of that software component.
Control abstraction abstracts away details of the actual control flow to focus on tasks at a simplified level.
print(“Hello”) is an abstraction of the actual output mechanism within the computer.
Abstraction can be applied repeatedly to obtain progressively higher levels of abstractions.
An example of different levels of data abstraction: a File is a data item that is at a higher level than an array and an array is at a higher level
than a bit.
An example of different levels of control abstraction: execute(Game) is at a higher level than print(Char) which is at a higher than
an Assembly language instruction MOV.
Can improve code quality using technique: make the happy path prominent
The happy path (i.e. the execution path taken when everything goes well) should be clear and prominent in your code. Restructure the code to make the happy path unindented as much as possible. It is the ‘unusual’ cases that should be indented. Someone reading the code should not get distracted by alternative paths taken when error conditions happen. One technique that could help in this regard is the use of guard clauses.
Example:
Bad
if (!isUnusualCase) { //detecting an unusual condition
if (!isErrorCase) {
start(); //main path
process();
cleanup();
exit();
} else {
handleError();
}
} else {
handleUnusualCase(); //handling that unusual condition
}
In the code above,
Good
if (isUnusualCase) { //Guard Clause
handleUnusualCase();
return;
}
if (isErrorCase) { //Guard Clause
handleError();
return;
}
start();
process();
cleanup();
exit();
In contrast, the above code
Can explain the need for following a standard
One essential way to improve code quality is to follow a consistent style. That is why software engineers follow a strict coding standard (aka style guide).
The aim of a coding standard is to make the entire code base look like it was written by one person. A coding standard is usually specific to a programming language and specifies guidelines such as the location of opening and closing braces, indentation styles and naming styles (e.g. whether to use Hungarian style, Pascal casing, Camel casing, etc.). It is important that the whole team/company use the same coding standard and that standard is not generally inconsistent with typical industry practices. If a company's coding standards is very different from what is used typically in the industry, new recruits will take longer to get used to the company's coding style.
💡 IDEs can help to enforce some parts of a coding standard e.g. indentation rules.
What is the recommended approach regarding coding standards?
c
What is the aim of using a coding standard? How does it help?
Can follow simple mechanical style rules
Learn basic guidelines of the Java coding standard (by OSS-Generic)
Sample coding standard: PEP 8 Python Style Guide -- by Python.org
Consider the code given below:
import java.util.*;
public class Task {
public static final String descriptionPrefix = "description: ";
private String description;
private boolean important;
List<String> pastDescription = new ArrayList<>(); // a list of past descriptions
public Task(String d) {
this.description = d;
if (!d.isEmpty())
this.important = true;
}
public String getAsXML() { return "<task>"+description+"</task>"; }
/**
* Print the description as a string.
*/
public void printingDescription(){ System.out.println(this); }
@Override
public String toString() { return descriptionPrefix + description; }
}
In what ways the code violate the basic guidelines (i.e., those marked with one ⭐️) of the OSS-Generic Java Coding Standard given here?
Here are three:
descriptionPrefix is a constant and should be named DESCRIPTION_PREFIXprintingDescription() should be named as printDescription()important should be named to sound boolean e.g., isImportantThere are many more.
Can follow intermediate style rules
Go through the provided Java coding standard and learn the intermediate style rules.
According to the given Java coding standard, which one of these is not a good name?
b
Explanation: checkWeight is an action. Naming variables as actions makes the code harder to follow. isWeightValid may be a better name.
Repeat the exercise in the panel below but also find violations of intermediate level guidelines.
Consider the code given below:
import java.util.*;
public class Task {
public static final String descriptionPrefix = "description: ";
private String description;
private boolean important;
List<String> pastDescription = new ArrayList<>(); // a list of past descriptions
public Task(String d) {
this.description = d;
if (!d.isEmpty())
this.important = true;
}
public String getAsXML() { return "<task>"+description+"</task>"; }
/**
* Print the description as a string.
*/
public void printingDescription(){ System.out.println(this); }
@Override
public String toString() { return descriptionPrefix + description; }
}
In what ways the code violate the basic guidelines (i.e., those marked with one ⭐️) of the OSS-Generic Java Coding Standard given here?
Here are three:
descriptionPrefix is a constant and should be named DESCRIPTION_PREFIXprintingDescription() should be named as printDescription()important should be named to sound boolean e.g., isImportantThere are many more.
Here's one you are more likely to miss:
* Print the description as a string. → * Prints the description as a string.There are more.
Can explain the need for good names in code
Proper naming improves the readability. It also reduces bugs caused by ambiguities regarding the intent of a variable or a method.
There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
Can improve code quality using technique: use nouns for things and verbs for actions
Use nouns for classes/variables and verbs for methods/functions.
Examples:
| Name for a | Bad | Good |
|---|---|---|
| Class | CheckLimit |
LimitChecker |
| method | result() |
calculate() |
Distinguish clearly between single-valued and multivalued variables.
Examples:
Good
Person student;
ArrayList<Person> students;
Good
student = Person('Jim')
students = [Person('Jim'), Person('Alice')]
Can improve code quality using technique: use standard words
Use correct spelling in names. Avoid 'texting-style' spelling. Avoid foreign language words, slang, and names that are only meaningful within specific contexts/times e.g. terms from private jokes, a TV show currently popular in your country
Can improve code quality using technique: use name to explain
A name is not just for differentiation; it should explain the named entity to the reader accurately and at a sufficient level of detail.
Examples:
| Bad | Good |
|---|---|
processInput() (what 'process'?) |
removeWhiteSpaceFromInput() |
flag |
isValidInput |
temp |
If the name has multiple words, they should be in a sensible order.
Examples:
| Bad | Good |
|---|---|
bySizeOrder() |
orderBySize() |
Imagine going to the doctor's and saying "My eye1 is swollen"! Don’t use numbers or case to distinguish names.
Examples:
| Bad | Bad | Good |
|---|---|---|
value1, value2 |
value, Value |
originalValue, finalValue |
Can improve code quality using technique: not too long, not too short
While it is preferable not to have lengthy names, names that are 'too short' are even worse. If you must abbreviate or use acronyms, do it consistently. Explain their full meaning at an obvious location.
Can improve code quality using technique: avoid misleading names
Related things should be named similarly, while unrelated things should NOT.
Example: Consider these variables
colorBlack : hex value for color blackcolorWhite : hex value for color whitecolorBlue : number of times blue is usedhexForRed : : hex value for color redThis is misleading because colorBlue is named similar to colorWhite and colorBlack but has a different purpose while hexForRed is named differently but
has very similar purpose to the first two variables. The following is better:
hexForBlack hexForWhite hexForRedblueColorCountAvoid misleading or ambiguous names (e.g. those with multiple meanings), similar sounding names, hard-to-pronounce ones (e.g. avoid ambiguities like "is that a lowercase L, capital I or number 1?", or "is that number 0 or letter O?"), almost similar names.
Examples:
| Bad | Good | Reason |
|---|---|---|
phase0 |
phaseZero |
Is that zero or letter O? |
rwrLgtDirn |
rowerLegitDirection |
Hard to pronounce |
right left wrong |
rightDirection leftDirection wrongResponse |
right is for 'correct' or 'opposite of 'left'? |
redBooks readBooks |
redColorBooks booksRead |
red and read (past tense) sounds the same |
FiletMignon |
egg |
If the requirement is just a name of a food, egg is a much easier to type/say choice than FiletMignon |
Can explain the need for avoiding error-prone shortcuts
It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Some such coding practices are common sources of bugs. Know them and avoid them.
Can improve code quality using technique: use the default branch
Always include a default branch in case statements.
Furthermore, use it for the intended default action and not just to execute the last option. If there is no default action, you can use the 'default' branch to detect errors (i.e. if execution reached the
default branch, throw an exception). This also applies to the final else of an if-else construct. That is, the final else should mean 'everything else',
and not the final option. Do not use else when an if condition can be explicitly specified, unless there is absolutely no other possibility.
Bad
if (red) print "red";
else print "blue";
Good
if (red) print "red";
else if (blue) print "blue";
else error("incorrect input");
Can improve code quality using technique: don't recycle variables or parameters
Bad
double computeRectangleArea(double length, double width) {
length = length * width;
return length;
}
Good
double computeRectangleArea(double length, double width) {
double area;
area = length * width;
return area;
}
Can improve code quality using technique: avoid empty catch blocks
Never write an empty catch statement. At least give a comment to explain why the catch block is left empty.
Can improve code quality using technique: delete dead code
We all feel reluctant to delete code we have painstakingly written, even if we have no use for that code any more ("I spent a lot of time writing that code; what if we need it again?"). Consider all code as baggage you have to carry; get rid of unused code the moment it becomes redundant. If you need that code again, simply recover it from the revision control tool you are using. Deleting code you wrote previously is a sign that you are improving.
Can improve code quality using technique: minimise scope of variables
Minimize global variables. Global variables may be the most convenient way to pass information around, but they do create implicit links between code segments that use the global variable. Avoid them as much as possible.
Define variables in the least possible scope. For example, if the variable is used only within the if block of the conditional statement, it should be declared inside that if block.
The most powerful technique for minimizing the scope of a local variable is to declare it where it is first used. -- Effective Java, by Joshua Bloch
Resources:
Can improve code quality using technique: minimise code duplication
Code duplication, especially when you copy-paste-modify code, often indicates a poor quality implementation. While it may not be possible to have zero duplication, always think twice before duplicating code; most often there is a better alternative.
This guideline is closely related to the
Supplmentary → Principles →
DRY (Don't Repeat Yourself) Principle: Every piece of knowledge must have a single, unambiguous, authoritative representation within a system The Pragmatic Programmer, by Andy Hunt and Dave Thomas
This principle guards against duplication of information.
The functionality implemented twice is a violation of the DRY principle even if the two implementations are different.
The value a system-wide timeout being defined in multiple places is a violation of DRY.
Can explain the need for commenting minimally but sufficiently
Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer. --Steve McConnell, Author of Clean Code
Some think commenting heavily increases the 'code quality'. This is not so. Avoid writing comments to explain bad code. Improve the code to make it self-explanatory.
Can improve code quality using technique: do not repeat the obvious
If the code is self-explanatory, refrain from repeating the description in a comment just for the sake of 'good documentation'.
Bad
// increment x
x++;
//trim the input
trimInput();
Can improve code quality using technique: write to the reader
Do not write comments as if they are private notes to self. Instead, write them well enough to be understood by another programmer. One type of comments that is almost always useful is the header comment that you write for a class or an operation to explain its purpose.
Examples:
Bad Reason: this comment will only make sense to the person who wrote it
// a quick trim function used to fix bug I detected overnight
void trimInput(){
....
}
Good
/** Trims the input of leading and trailing spaces */
void trimInput(){
....
}
Bad Reason: this comment will only make sense to the person who wrote it
# a quick trim function used to fix bug I detected overnight
def trim_input():
...
Good
def trim_input():
"""Trim the input of leading and trailing spaces"""
...
Can improve code quality using technique: explain what and why, not how
Comments should explain what and why aspect of the code, rather than the how aspect.
👍 What : The specification of what the code supposed to do. The reader can compare such comments to the implementation to verify if the implementation is correct
Example: This method is possibly buggy because the implementation does not seem to match the comment. In this case the comment could help the reader to detect the bug.
/** Removes all spaces from the {@code input} */
void compact(String input){
input.trim();
}
👍 Why : The rationale for the current implementation.
Example: Without this comment, the reader will not know the reason for calling this method.
// Remove spaces to comply with IE23.5 formatting rules
compact(input);
👎 How : The explanation for how the code works. This should already be apparent from the code, if the code is self-explanatory. Adding comments to explain the same thing is redundant.
Example:
Bad Reason: Comment explains how the code works.
// return true if both left end and right end are correct or the size has not incremented
return (left && right) || (input.size() == size);
Good Reason: Code refactored to be self-explanatory. Comment no longer needed.
boolean isSameSize = (input.size() == size) ;
return (isLeftEndCorrect && isRightEndCorrect) || isSameSize;
null
B. Depth and completeness of the major feature
Evaluates: How good is your Quality Assurance?
Based on: 1. your test code 2. our own manual testing 3. your performance in the two Practical Exams (PE), 4. bugs found during PE.
Relevant: [
What: The v1.3 is subjected to a round of peer acceptance/system testing, also called the Practical Exam Round 1 (PE-1). This round of testing will be graded similar to the
When, where: 45 minute slot at the end of week 11 lecture, in the Lecture venue
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2:
nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough
details rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands
edit, undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students
to be have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given
below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You
can also reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility.
If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Grading: Taking part in the PE-1 is strongly encouraged as it can affect your grade in the following ways.
Objectives:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During the session:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP.
Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written
by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
After the session:
Relevant: [
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2: nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough details
rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands edit,
undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students
to be have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You can
also reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility.
If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Evaluates: How well does your user guide achieves its objectives?
Based on: the relevant sections of your project portfolio. Criteria considered:
A. Process:
Evaluates: How well you did in project management related aspects of the project, as an individual and as a team
Based on: Supervisor observations of project milestones and GitHub data.
Milestones need to be reached the midnight before of the tutorial for it to be counted as achieved. To get a good grade this aspect, achieve recommended weekly progress in at least 6/10 weeks.
Other criteria:
B. Team-based tasks:
Evaluates: How much you contributed to common team-based tasks
Based on: peer evaluations and tutor observations
Relevant: [
Here is a non-exhaustive list of team-tasks:
Your tutor will serve as your project supervisor too.
The supervisor's main job is to observe, facilitate self/peer learning, evaluate, and give feedback.
Tutorial time is the main avenue for meeting your supervisor. In addition, you can meet the supervisor before/after the tutorial, or any other time, as many times you need, subject to availability in his/her schedule.
Note that it is not the supervisor’s job to chase you down and give help. It is up to you to get as much feedback from them as you need. You are free to request more feedback from the supervisor as necessary. Similarly, it is not the job of the supervisor to lead your project to success.
We use the TEAMMATES online peer evaluation system to conduct several rounds of peer-evaluations. All peer evaluations will be taken into account when determining your participation marks. The system also allows you to give anonymous feedback to your teammates.
Extra Requirements: [considered for participation marks]
The purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly -- somewhat similar to a passport photo. Some examples can be seen in the 'Teaching
team' page. Given below are some examples of good and bad profile photos.
If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.
Peer evaluation criteria: professional conduct
Peer evaluation criteria: competency
Giving constructive feedback to others is a valuable skill for software engineers. It is also an intended learning outcome of this module. Half-hearted/trivial feedback will not earn participation marks.
Here are some things to keep in mind:
Thanks for all the hard work! and negative ratings (e.g. Equal share - 40%) to the same team member is not being honest.The final peer evaluation (in week 13) is graded. In that peer-evaluation you will be asked to evaluate the work of your team members and another team. The quality and accuracy of your evaluation will affect your grade and your evaluations will be considered as a data point in determining the grade of the team members.
Learning Management System: This module website is the main source of information for the module. In addition, we use IVLE for some things (e.g., announcements, file submissions, grade book, ...) and LumiNUS for lecture webcasts (reason: IVLE no longer supports webcasts).
Collaboration platform: You are required to use GitHub as the hosting and collaboration platform of your project (i.e., to hold the Code repository, Issue Tracker, etc.). See Appendix E for more info on how to setup and use GitHub for your project.
Communication: Keeping a record of communications among your team can help you, and us, in many ways. We encourage you to do at least some of the project communication in written medium (e.g., GitHub Issue Tracker) to practice how to communicate technical things in written form.
@nus.edu.sg, @comp.nus.edu.sg, or @u.nus.edu to join this channel).IDE: You are recommended to use Intellij IDEA for module-related programming work. You may use the community edition (free) or the ultimate edition (free for students). While the use of Intellij is not compulsory, note that module materials are optimized for Intellij. Use other IDEs at your own risk.
Revision control: You are required to use Git. Other revision control software are not allowed.
The recommended GUI client for Git is SourceTree (which
comes bundled with Git), but you may use any other, or none.
Analyzing code authorship: We use a custom-built tool called RepoSense for extracting code written by each person.
In previous semesters we asked students to annotate all their code using special @@author tags so that we can extract each student's code for grading. This semester, we are trying out a new tool called RepoSense that is
expected to reduce the need for such tagging, and also make it easier for you to see (and learn from) code written by others.
1. View the current status of code authorship data:
2. If the code does not match:
Here are the possible reasons for the code shown not to match the code you wrote:
In those cases,
config.json file to your repo (as specified by one of the two methods),
"authorNames": ["theMyth", "theLegend", "theGary"]config.json in the .gitignore file of your repo as /config.json so that it ignores the config.json produced by the app but not the _reposense/config.json.@@author annotations, please follow the guidelines below:@@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 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.
config.json file you added and/or the annotated code to your repo. We'll use that information the next time we
run RepoSense (we run it at least once a week).We recommend you ensure your code is RepoSense-compatible by v1.3
Relevant: [
10 marks allocated for participation can be earned in the following ways (there are ~28 available marks to choose from):
Relevant: [
Peer evaluation criteria: professional conduct
Peer evaluation criteria: competency
Relevant: [
There is no midterm.
The final exam has two parts:
Both papers will be given to you at the start but you need to answer Part 1 first (i.e. MCQ paper). It will be collected 30 min after the exam start time (even if arrived late for the exam). You are free to start part 2 early if you finish Part 1 early.
Each MCQ question gives you a statement to evaluate.
An example statement
Testing is a Q&A activity
Unless stated otherwise, the meaning of answer options are
A. True
B. False
The exam paper has 50 questions. All questions carry equal marks.
The weightage of the Part 1 of the final exam is 25 marks out of the total score of 100.
Note that you have slightly more than ½ minute for each question, which means you need to go through the questions fairly quickly.
Given the fast pace required by the paper, to be fair to all students, you will not be allowed to clarify doubts about questions (in Part 1) by talking to invigilators.
Questions in Part 1 are confidential. You are not allowed to reveal Part 1 content to anyone after the exam. All pages of the assessment paper are to be returned at the end of the exam.
You will be given OCR forms to indicate your answers for Part 1.
The paper is open-book: you may bring any printed or written materials to the exam in hard copy format. However, given the fast pace required by Part 1, you will not have time left to refer notes during that part of the exam.
💡 Mark the OCR form as you go, rather than planning to transfer your answers to the OCR form near the end. Reason: Given there are 50 questions and only 30 mins, it will be hard to estimate how much time you need to mass-transfer all answers to OCR forms.
💡 Write the answer in the exam paper as well as marking it in the OCR form. Reason: It will reduce the chance of missing a question. Furthermore, in case you missed a question, it will help you correct the OCR form quickly.
💡 We have tried to avoid deliberately misleading/tricky questions. If a question seems to take a very long time to figure out, you are probably over-thinking it.
Unlike in part 1, you can ask invigilators for clarifications if you found a question to be unclear in part 2.
Yes, you may use pencils when answering part 2.
The weightage of the Part 2 of the final exam is 15 marks out of the total score of 100.
Past exam papers uploaded on IVLE
Relevant: [
Note that project grading is not competitive (not bell curved). CS2113T projects will be assessed separately from CS2113 projects. This is to account for the perceived difference in workload. Given below is the marking scheme.
Total: 50 marks ( 40 individual marks + 10 team marks)
Evaluates: How well do your features fit together to form a cohesive product (not how many features or how big the features are)?
Based on: user guide and the product demo. The quality of the demo will be factored in as well.
❗️ Feature that fits well with the other features will earn more marks.
Evaluates:
A. Code quality/quantity:
How good your implementation is, in terms of the quality and the quantity of the code you have written yourself.
Based on: an inspection of the collated code (obtained from Reposense).
Ensure your code has at least some evidence of these (see here for more info)
Ensure there are 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.
Ensure SLAP is applied at a reasonable level. Long methods or deeply-nested code are symptoms of low-SLAP may be counted against your code quality.
Reduce 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.
In addition, try to apply as many of the
Can explain the importance of code quality
Always code as if the person who ends up maintaining your code will be a violent psychopath who knows where you live. -- Martin Golding
Can explain the importance of readability
Programs should be written and polished until they acquire publication quality. --Niklaus Wirth
Among various dimensions of code quality, such as run-time efficiency, security, and robustness, one of the most important is understandability. This is because in any non-trivial software project, code needs to be read, understood, and modified by other developers later on. Even if we do not intend to pass the code to someone else, code quality is still important because we all become 'strangers' to our own code someday.
The two code samples given below achieve the same functionality, but one is easier to read.
|
Bad |
|
Good |
|
Bad |
|
Good |
Can improve code quality using technique: avoid long methods
Be wary when a method is longer than the computer screen, and take corrective action when it goes beyond 30 LOC (lines of code). The bigger the haystack, the harder it is to find a needle.
Can improve code quality using technique: avoid deep nesting
If you need more than 3 levels of indentation, you're screwed anyway, and should fix your program. --Linux 1.3.53 CodingStyle
In particular, avoid arrowhead style code.
Example:
Can improve code quality using technique: avoid complicated expressions
Avoid complicated expressions, especially those having many negations and nested parentheses. If you must evaluate complicated expressions, have it done in steps (i.e. calculate some intermediate values first and use them to calculate the final value).
Example:
Bad
return ((length < MAX_LENGTH) || (previousSize != length)) && (typeCode == URGENT);
Good
boolean isWithinSizeLimit = length < MAX_LENGTH;
boolean isSameSize = previousSize != length;
boolean isValidCode = isWithinSizeLimit || isSameSize;
boolean isUrgent = typeCode == URGENT;
return isValidCode && isUrgent;
Example:
Bad
return ((length < MAX_LENGTH) or (previous_size != length)) and (type_code == URGENT)
Good
is_within_size_limit = length < MAX_LENGTH
is_same_size = previous_size != length
is_valid_code = is_within_size_limit or is_same_size
is_urgent = type_code == URGENT
return is_valid_code and is_urgent
The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague. -- Edsger Dijkstra
Can improve code quality using technique: avoid magic numbers
When the code has a number that does not explain the meaning of the number, we call that a magic number (as in “the number appears as if by magic”). Using a
Example:
|
Bad |
|
Good |
Note: Python does not have a way to make a variable a constant. However, you can use a normal variable with an ALL_CAPS name to simulate a constant.
|
Bad |
|
Good |
Similarly, we can have ‘magic’ values of other data types.
Bad
"Error 1432" // A magic string!
Can improve code quality using technique: make the code obvious
Make the code as explicit as possible, even if the language syntax allows them to be implicit. Here are some examples:
Java] Use explicit type conversion instead of implicit type conversion.Java, Python] Use parentheses/braces to show grouping even when they can be skipped.Java, Python] Use
SystemState and define an enumeration SystemState that has values 'STARTING',
'ENABLED', and 'DISABLED'.Can improve code quality using technique: structure code logically
Lay out the code so that it adheres to the logical structure. The code should read like a story. Just like we use section breaks, chapters and paragraphs to organize a story, use classes, methods, indentation and line spacing in your code to group related segments of the code. For example, you can use blank lines to group related statements together. Sometimes, the correctness of your code does not depend on the order in which you perform certain intermediary steps. Nevertheless, this order may affect the clarity of the story you are trying to tell. Choose the order that makes the story most readable.
Can improve code quality using technique: do not 'trip up' reader
Avoid things that would make the reader go ‘huh?’, such as,
Can improve code quality using technique: practice kissing
As the old adage goes, "keep it simple, stupid” (KISS). Do not try to write ‘clever’ code. For example, do not dismiss the brute-force yet simple solution in favor of a complicated one because of some ‘supposed benefits’ such as 'better reusability' unless you have a strong justification.
Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. --Brian W. Kernighan
Programs must be written for people to read, and only incidentally for machines to execute. --Abelson and Sussman
Can improve code quality using technique: avoid premature optimizations
Optimizing code prematurely has several drawbacks:
A popular saying in the industry is make it work, make it right, make it fast which means in most cases getting the code to perform correctly should take priority over optimizing it. If the code doesn't work correctly, it has no value on matter how fast/efficient it it.
Premature optimization is the root of all evil in programming. --Donald Knuth
Note that there are cases where optimizing takes priority over other things e.g. when writing code for resource-constrained environments. This guideline simply a caution that you should optimize only when it is really needed.
Can improve code quality using technique: SLAP hard
Avoid varying the level of
Example:
Bad
readData();
salary = basic*rise+1000;
tax = (taxable?salary*0.07:0);
displayResult();
Good
readData();
processData();
displayResult();
Design → Design Fundamentals → Abstraction →
Abstraction is a technique for dealing with complexity. It works by establishing a level of complexity (or an aspect) we are interested in, and suppressing the more complex details below that level (or irrelevant to that aspect).
Most programs are written to solve complex problems involving large amounts of intricate details. It is impossible to deal with all these details at the same time. The guiding principle of abstraction stipulates that we capture only details that are relevant to the current perspective or the task at hand.
Ignoring lower level data items and thinking in terms of bigger entities is called data abstraction.
Within a certain software component, we might deal with a user data type, while ignoring the details contained in the user data item such as name, and date of birth. These details have been ‘abstracted away’ as they do not affect the task of that software component.
Control abstraction abstracts away details of the actual control flow to focus on tasks at a simplified level.
print(“Hello”) is an abstraction of the actual output mechanism within the computer.
Abstraction can be applied repeatedly to obtain progressively higher levels of abstractions.
An example of different levels of data abstraction: a File is a data item that is at a higher level than an array and an array is at a higher level
than a bit.
An example of different levels of control abstraction: execute(Game) is at a higher level than print(Char) which is at a higher than
an Assembly language instruction MOV.
Can improve code quality using technique: make the happy path prominent
The happy path (i.e. the execution path taken when everything goes well) should be clear and prominent in your code. Restructure the code to make the happy path unindented as much as possible. It is the ‘unusual’ cases that should be indented. Someone reading the code should not get distracted by alternative paths taken when error conditions happen. One technique that could help in this regard is the use of guard clauses.
Example:
Bad
if (!isUnusualCase) { //detecting an unusual condition
if (!isErrorCase) {
start(); //main path
process();
cleanup();
exit();
} else {
handleError();
}
} else {
handleUnusualCase(); //handling that unusual condition
}
In the code above,
Good
if (isUnusualCase) { //Guard Clause
handleUnusualCase();
return;
}
if (isErrorCase) { //Guard Clause
handleError();
return;
}
start();
process();
cleanup();
exit();
In contrast, the above code
Can explain the need for following a standard
One essential way to improve code quality is to follow a consistent style. That is why software engineers follow a strict coding standard (aka style guide).
The aim of a coding standard is to make the entire code base look like it was written by one person. A coding standard is usually specific to a programming language and specifies guidelines such as the location of opening and closing braces, indentation styles and naming styles (e.g. whether to use Hungarian style, Pascal casing, Camel casing, etc.). It is important that the whole team/company use the same coding standard and that standard is not generally inconsistent with typical industry practices. If a company's coding standards is very different from what is used typically in the industry, new recruits will take longer to get used to the company's coding style.
💡 IDEs can help to enforce some parts of a coding standard e.g. indentation rules.
What is the recommended approach regarding coding standards?
c
What is the aim of using a coding standard? How does it help?
Can follow simple mechanical style rules
Learn basic guidelines of the Java coding standard (by OSS-Generic)
Sample coding standard: PEP 8 Python Style Guide -- by Python.org
Consider the code given below:
import java.util.*;
public class Task {
public static final String descriptionPrefix = "description: ";
private String description;
private boolean important;
List<String> pastDescription = new ArrayList<>(); // a list of past descriptions
public Task(String d) {
this.description = d;
if (!d.isEmpty())
this.important = true;
}
public String getAsXML() { return "<task>"+description+"</task>"; }
/**
* Print the description as a string.
*/
public void printingDescription(){ System.out.println(this); }
@Override
public String toString() { return descriptionPrefix + description; }
}
In what ways the code violate the basic guidelines (i.e., those marked with one ⭐️) of the OSS-Generic Java Coding Standard given here?
Here are three:
descriptionPrefix is a constant and should be named DESCRIPTION_PREFIXprintingDescription() should be named as printDescription()important should be named to sound boolean e.g., isImportantThere are many more.
Can follow intermediate style rules
Go through the provided Java coding standard and learn the intermediate style rules.
According to the given Java coding standard, which one of these is not a good name?
b
Explanation: checkWeight is an action. Naming variables as actions makes the code harder to follow. isWeightValid may be a better name.
Repeat the exercise in the panel below but also find violations of intermediate level guidelines.
Consider the code given below:
import java.util.*;
public class Task {
public static final String descriptionPrefix = "description: ";
private String description;
private boolean important;
List<String> pastDescription = new ArrayList<>(); // a list of past descriptions
public Task(String d) {
this.description = d;
if (!d.isEmpty())
this.important = true;
}
public String getAsXML() { return "<task>"+description+"</task>"; }
/**
* Print the description as a string.
*/
public void printingDescription(){ System.out.println(this); }
@Override
public String toString() { return descriptionPrefix + description; }
}
In what ways the code violate the basic guidelines (i.e., those marked with one ⭐️) of the OSS-Generic Java Coding Standard given here?
Here are three:
descriptionPrefix is a constant and should be named DESCRIPTION_PREFIXprintingDescription() should be named as printDescription()important should be named to sound boolean e.g., isImportantThere are many more.
Here's one you are more likely to miss:
* Print the description as a string. → * Prints the description as a string.There are more.
Can explain the need for good names in code
Proper naming improves the readability. It also reduces bugs caused by ambiguities regarding the intent of a variable or a method.
There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
Can improve code quality using technique: use nouns for things and verbs for actions
Use nouns for classes/variables and verbs for methods/functions.
Examples:
| Name for a | Bad | Good |
|---|---|---|
| Class | CheckLimit |
LimitChecker |
| method | result() |
calculate() |
Distinguish clearly between single-valued and multivalued variables.
Examples:
Good
Person student;
ArrayList<Person> students;
Good
student = Person('Jim')
students = [Person('Jim'), Person('Alice')]
Can improve code quality using technique: use standard words
Use correct spelling in names. Avoid 'texting-style' spelling. Avoid foreign language words, slang, and names that are only meaningful within specific contexts/times e.g. terms from private jokes, a TV show currently popular in your country
Can improve code quality using technique: use name to explain
A name is not just for differentiation; it should explain the named entity to the reader accurately and at a sufficient level of detail.
Examples:
| Bad | Good |
|---|---|
processInput() (what 'process'?) |
removeWhiteSpaceFromInput() |
flag |
isValidInput |
temp |
If the name has multiple words, they should be in a sensible order.
Examples:
| Bad | Good |
|---|---|
bySizeOrder() |
orderBySize() |
Imagine going to the doctor's and saying "My eye1 is swollen"! Don’t use numbers or case to distinguish names.
Examples:
| Bad | Bad | Good |
|---|---|---|
value1, value2 |
value, Value |
originalValue, finalValue |
Can improve code quality using technique: not too long, not too short
While it is preferable not to have lengthy names, names that are 'too short' are even worse. If you must abbreviate or use acronyms, do it consistently. Explain their full meaning at an obvious location.
Can improve code quality using technique: avoid misleading names
Related things should be named similarly, while unrelated things should NOT.
Example: Consider these variables
colorBlack : hex value for color blackcolorWhite : hex value for color whitecolorBlue : number of times blue is usedhexForRed : : hex value for color redThis is misleading because colorBlue is named similar to colorWhite and colorBlack but has a different purpose while hexForRed is named differently but
has very similar purpose to the first two variables. The following is better:
hexForBlack hexForWhite hexForRedblueColorCountAvoid misleading or ambiguous names (e.g. those with multiple meanings), similar sounding names, hard-to-pronounce ones (e.g. avoid ambiguities like "is that a lowercase L, capital I or number 1?", or "is that number 0 or letter O?"), almost similar names.
Examples:
| Bad | Good | Reason |
|---|---|---|
phase0 |
phaseZero |
Is that zero or letter O? |
rwrLgtDirn |
rowerLegitDirection |
Hard to pronounce |
right left wrong |
rightDirection leftDirection wrongResponse |
right is for 'correct' or 'opposite of 'left'? |
redBooks readBooks |
redColorBooks booksRead |
red and read (past tense) sounds the same |
FiletMignon |
egg |
If the requirement is just a name of a food, egg is a much easier to type/say choice than FiletMignon |
Can explain the need for avoiding error-prone shortcuts
It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Some such coding practices are common sources of bugs. Know them and avoid them.
Can improve code quality using technique: use the default branch
Always include a default branch in case statements.
Furthermore, use it for the intended default action and not just to execute the last option. If there is no default action, you can use the 'default' branch to detect errors (i.e. if execution reached the
default branch, throw an exception). This also applies to the final else of an if-else construct. That is, the final else should mean 'everything else',
and not the final option. Do not use else when an if condition can be explicitly specified, unless there is absolutely no other possibility.
Bad
if (red) print "red";
else print "blue";
Good
if (red) print "red";
else if (blue) print "blue";
else error("incorrect input");
Can improve code quality using technique: don't recycle variables or parameters
Bad
double computeRectangleArea(double length, double width) {
length = length * width;
return length;
}
Good
double computeRectangleArea(double length, double width) {
double area;
area = length * width;
return area;
}
Can improve code quality using technique: avoid empty catch blocks
Never write an empty catch statement. At least give a comment to explain why the catch block is left empty.
Can improve code quality using technique: delete dead code
We all feel reluctant to delete code we have painstakingly written, even if we have no use for that code any more ("I spent a lot of time writing that code; what if we need it again?"). Consider all code as baggage you have to carry; get rid of unused code the moment it becomes redundant. If you need that code again, simply recover it from the revision control tool you are using. Deleting code you wrote previously is a sign that you are improving.
Can improve code quality using technique: minimise scope of variables
Minimize global variables. Global variables may be the most convenient way to pass information around, but they do create implicit links between code segments that use the global variable. Avoid them as much as possible.
Define variables in the least possible scope. For example, if the variable is used only within the if block of the conditional statement, it should be declared inside that if block.
The most powerful technique for minimizing the scope of a local variable is to declare it where it is first used. -- Effective Java, by Joshua Bloch
Resources:
Can improve code quality using technique: minimise code duplication
Code duplication, especially when you copy-paste-modify code, often indicates a poor quality implementation. While it may not be possible to have zero duplication, always think twice before duplicating code; most often there is a better alternative.
This guideline is closely related to the
Supplmentary → Principles →
DRY (Don't Repeat Yourself) Principle: Every piece of knowledge must have a single, unambiguous, authoritative representation within a system The Pragmatic Programmer, by Andy Hunt and Dave Thomas
This principle guards against duplication of information.
The functionality implemented twice is a violation of the DRY principle even if the two implementations are different.
The value a system-wide timeout being defined in multiple places is a violation of DRY.
Can explain the need for commenting minimally but sufficiently
Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer. --Steve McConnell, Author of Clean Code
Some think commenting heavily increases the 'code quality'. This is not so. Avoid writing comments to explain bad code. Improve the code to make it self-explanatory.
Can improve code quality using technique: do not repeat the obvious
If the code is self-explanatory, refrain from repeating the description in a comment just for the sake of 'good documentation'.
Bad
// increment x
x++;
//trim the input
trimInput();
Can improve code quality using technique: write to the reader
Do not write comments as if they are private notes to self. Instead, write them well enough to be understood by another programmer. One type of comments that is almost always useful is the header comment that you write for a class or an operation to explain its purpose.
Examples:
Bad Reason: this comment will only make sense to the person who wrote it
// a quick trim function used to fix bug I detected overnight
void trimInput(){
....
}
Good
/** Trims the input of leading and trailing spaces */
void trimInput(){
....
}
Bad Reason: this comment will only make sense to the person who wrote it
# a quick trim function used to fix bug I detected overnight
def trim_input():
...
Good
def trim_input():
"""Trim the input of leading and trailing spaces"""
...
Can improve code quality using technique: explain what and why, not how
Comments should explain what and why aspect of the code, rather than the how aspect.
👍 What : The specification of what the code supposed to do. The reader can compare such comments to the implementation to verify if the implementation is correct
Example: This method is possibly buggy because the implementation does not seem to match the comment. In this case the comment could help the reader to detect the bug.
/** Removes all spaces from the {@code input} */
void compact(String input){
input.trim();
}
👍 Why : The rationale for the current implementation.
Example: Without this comment, the reader will not know the reason for calling this method.
// Remove spaces to comply with IE23.5 formatting rules
compact(input);
👎 How : The explanation for how the code works. This should already be apparent from the code, if the code is self-explanatory. Adding comments to explain the same thing is redundant.
Example:
Bad Reason: Comment explains how the code works.
// return true if both left end and right end are correct or the size has not incremented
return (left && right) || (input.size() == size);
Good Reason: Code refactored to be self-explanatory. Comment no longer needed.
boolean isSameSize = (input.size() == size) ;
return (isLeftEndCorrect && isRightEndCorrect) || isSameSize;
null
B. Depth and completeness of the major feature
Evaluates: How good is your Quality Assurance?
Based on: 1. your test code 2. our own manual testing 3. your performance in the two Practical Exams (PE), 4. bugs found during PE.
Relevant: [
What: The v1.3 is subjected to a round of peer acceptance/system testing, also called the Practical Exam Round 1 (PE-1). This round of testing will be graded similar to the
When, where: 45 minute slot at the end of week 11 lecture, in the Lecture venue
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2:
nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough
details rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands
edit, undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students
to be have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given
below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You
can also reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility.
If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Grading: Taking part in the PE-1 is strongly encouraged as it can affect your grade in the following ways.
Objectives:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2:
nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During the session:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
At the end of the project each student is required to submit a Project Portfolio Page.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your
PPP. Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is
written by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
After the session:
Relevant: [
Objectives:
When, where: Week 13 lecture
Grading:
Preparation:
Ensure that you can access the relevant issue tracker given below:
-- for PE-1: nusCS2113-AY1819S1/pe-1
-- for PE-2:
nusCS2113-AY1819S1/pe-2
Ensure you have access to a computer that is able to run module projects e.g. has the right Java version.
Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
Charge your computer before coming to the PE session. The testing venue may not have enough charging points.
During:
What to test:
help command).What not to test:
These are considered bugs:
Where to report bugs: Post bug in the following issue trackers (not in the team's repo):
Bug report format:
severity.Low (lower severity bugs earn lower credit):Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.About posting suggestions:
If the product doesn't work at all: If the product fails catastrophically e.g., cannot even launch, contact the lecturer immediately to obtain a new product to test.
[~45 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.
A. Cohesiveness of product features []: Do the features fit together and match the stated target user and the value proposition?
unable to judge: You are unable to judge this aspect for some reason.low: One of these
medium: Some features fit together but some don't.high: All features fit together but the features are not very high value to the target user.excellent: The target user is clearly defined (not too general) and almost all new features are of high-value to the target user. i.e. the product is very attractive to the target user.B. Quality of user docs []: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.
unable to judge: Less than 1 page worth of UG content written by the student.low: Hard to understand, often inaccurate or missing important information.medium: Needs some effort to understand; some information is missing.high: Mostly easy to follow. Only a few areas need improvements.excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).C. Quality of developer docs []: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.
unable to judge: One of these
low: One of these
medium: Some diagrams, some descriptions, but does not help the reader that much e.g. overly complicated diagrams.high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough details
rather than very complicated diagrams that are hard to understand.D. Depth of feature []: Evaluate the feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have the commands edit,
undo, and redo.
unable to judge: You are unable to judge this aspect for some reason.low : An easy feature e.g. make the existing find command case insensitive.medium : Moderately difficult feature, barely acceptable implementation e.g. an edit command that requires the user to type all fields, even the ones that are not being edited.high: One of the below
excellent: A difficult feature, all reasonable aspects are fully implemented undo/redo command that allows multiple undo/redo.E. Amount of work []: Evaluate the amount of work, on a scale of 0 to 30.
history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students
to be have efforts lower than 20.Bug Review Period:
There will be a review period for you to respond to the bug reports you received.
Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Tuesday midnight.
Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.
Instructions for Reviewing Bug Reports
First, don't freak out if there are lot of bug reports. Many can be duplicates and some can be false positives. In any case, we anticipate that all of these products will have some bugs and our penalty for bugs is not harsh. Furthermore, it depends on the severity of the bug. Some bug may not even be penalized.
Do not edit the subject or the description. Do not close bug reports. Your response (if any) should be added as a comment.
If the bug is reported multiple times, mark all copies EXCEPT one as duplicates using the duplicate tag (if the duplicates have different severity levels, you should keep the one with the highest severity).
In addition, use this technique to indicate which issue they are duplicates of. Duplicates can be omitted from processing steps given
below.
If a bug seems to be for a different product (i.e. wrongly assigned to your team), let us know (email prof).
Decide if it is a real bug and apply ONLY one of these labels.
Response Labels:
response.Accepted : You accept it as a bug.response.Rejected : What tester thought as a bug is in fact expected behavior. ❗️ The penalty for rejecting a bug using an unjustifiable explanation is higher than the penalty if the same bug was accepted. You can
also reject bugs that you inherited from AB4.response.CannotReproduce : You are unable to reproduce the behavior reported in the bug after multiple tries.response.IssueUnclear : The issue description is not clear.type- are considered type-FunctionalityBug by default (which are liable to a heavier penalty):Bug Type Labels:
type-FunctionalityBug : the bug is a flaw in how the product works.type-DocumentationBug : the bug is in the documentation.Bug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Decide who should fix the bug. Use the Assignees field to assign the issue to that person(s). There is no need to actually fix the bug though. It's simply an indication/acceptance of responsibility.
If there is no assignee, we will distribute the penalty for that bug (if any) among all team members.
Add an explanatory comment explaining your choice of labels and assignees.
Evaluates: How well does your user guide achieves its objectives?
Based on: the relevant sections of your project portfolio. Criteria considered:
A. Process:
Evaluates: How well you did in project management related aspects of the project, as an individual and as a team
Based on: Supervisor observations of project milestones and GitHub data.
Milestones need to be reached the midnight before of the tutorial for it to be counted as achieved. To get a good grade this aspect, achieve recommended weekly progress in at least 6/10 weeks.
Other criteria:
B. Team-based tasks:
Evaluates: How much you contributed to common team-based tasks
Based on: peer evaluations and tutor observations
Relevant: [
Here is a non-exhaustive list of team-tasks:
There is no midterm.
The final exam has two parts:
Both papers will be given to you at the start but you need to answer Part 1 first (i.e. MCQ paper). It will be collected 30 min after the exam start time (even if arrived late for the exam). You are free to start part 2 early if you finish Part 1 early.
Each MCQ question gives you a statement to evaluate.
An example statement
Testing is a Q&A activity
Unless stated otherwise, the meaning of answer options are
A. True
B. False
The exam paper has 50 questions. All questions carry equal marks.
The weightage of the Part 1 of the final exam is 25 marks out of the total score of 100.
Note that you have slightly more than ½ minute for each question, which means you need to go through the questions fairly quickly.
Given the fast pace required by the paper, to be fair to all students, you will not be allowed to clarify doubts about questions (in Part 1) by talking to invigilators.
Questions in Part 1 are confidential. You are not allowed to reveal Part 1 content to anyone after the exam. All pages of the assessment paper are to be returned at the end of the exam.
You will be given OCR forms to indicate your answers for Part 1.
The paper is open-book: you may bring any printed or written materials to the exam in hard copy format. However, given the fast pace required by Part 1, you will not have time left to refer notes during that part of the exam.
💡 Mark the OCR form as you go, rather than planning to transfer your answers to the OCR form near the end. Reason: Given there are 50 questions and only 30 mins, it will be hard to estimate how much time you need to mass-transfer all answers to OCR forms.
💡 Write the answer in the exam paper as well as marking it in the OCR form. Reason: It will reduce the chance of missing a question. Furthermore, in case you missed a question, it will help you correct the OCR form quickly.
💡 We have tried to avoid deliberately misleading/tricky questions. If a question seems to take a very long time to figure out, you are probably over-thinking it.
Unlike in part 1, you can ask invigilators for clarifications if you found a question to be unclear in part 2.
Yes, you may use pencils when answering part 2.
The weightage of the Part 2 of the final exam is 15 marks out of the total score of 100.
Past exam papers uploaded on IVLE
10 marks allocated for participation can be earned in the following ways (there are ~28 available marks to choose from):
Relevant: [
Peer evaluation criteria: professional conduct
Peer evaluation criteria: competency
These are some of the main principles underlying the module structure.
The software product you build is a side effect only. You are the product of this module. This means,
Following from that, we evaluate you on not just how much you've done, but also, how well you've done those things. Here are some of the aspects in which we focus on:
|
We appreciate ... |
But we value more ... |
|
Ability to deal with low-level details |
Ability to abstract over details, generalize, see the big picture |
|
A drive to learn latest and greatest technologies |
Ability to make the best of given tools |
|
Ability to find problems that interest you and solve them |
Ability to solve the given problem to the best of your ability |
|
Ability to burn the midnight oil to meet a deadline |
Ability to schedule work so that the need for 'last minute heroics' is minimal |
|
Preference to do things you like or things you are good at |
Ability to buckle down and deliver on important things that you don't necessarily like or aren't good at |
|
Ability to deliver desired end results |
Ability to deliver in a way that shows how well you delivered (i.e. visibility of your work) |
We learn together, NOT compete against each other.
You are not in a competition. Our grading is not forced on a bell curve.
Learn from each other. That is why we open-source your submissions.
Teach each other, even those in other teams. Those who do it well can become tutors next time.
Continuously engage, NOT last minute heroics.
We want to train you to do software engineering in a steady and repeatable manner that does not require 'last minute heroics'.
In this module, last minute heroics will not earn you a good project grade, and last minute mugging will not earn you a good exam grade.
Where you reach at the end matters, NOT what you knew at the beginning.
When you start the module, some others in the class may appear to know a lot more than you. Don't let that worry you. The final grade depends on what you know at the end, not what you knew to begin with. All marks allocated to intermediate deliverables are within the reach of everyone in the class irrespective of their prior knowledge.
When working with others, especially in a large class such as CS2113/T, it is very important that you adhere to standards, policies, and instructions imposed on everyone. Not doing so creates unnecessary headaches for everyone and puts your work attitude in a negative light. That is why we penalize repeated violations of instructions. On the other hand we do understand that humans are liable to make mistakes. That is why we only penalize repeated or frequent mistakes.
As most of the work is graded individually, team sizes of 3, 4, or 5 is not expected to affect your grade. While managing larger teams is harder, larger teams have more collective know-how, which can cancel each other.
As most of the work is graded individually, it is OK to do less or more than equal share in your project team.
Related: [Admin: Project: Scope]
There is no need to inform us. If you miss a lecture/tutorial for a valid reason, just do your best to catch up. We'll be happy to help if required. An occasional absence or two is not expected to affect your participation marks.
Only if you fail to earn full marks for participation we will consider giving an alternative avenue to earn marks missed due to the absences.
Normally, the prof will respond within 24 hours if it was an email sent to the prof or a forum post directed at the prof. If you don't get a response within that time, please feel free to remind the prof. It is likely that the prof did not notice your post or the email got stuck somewhere.
Similarly we expect you to check email regularly and respond to emails written to you personally (not mass email) promptly.
Not responding to a personal email is a major breach of professional etiquette (and general civility). Imagine how pissed off you would be if you met the prof along the corridor, said 'Hi prof, good morning' and the prof walked away without saying anything back. Not responding to a personal email is just as bad. Always take a few seconds to at least acknowledge such emails. It doesn't take long to type "Noted. Thanks" and hit 'send'.
The promptness of a reply is even more important when the email is requesting you for something that you cannot provide. Imagine you wrote to the prof requesting a reference letter and the prof did not respond at all because he/she did not want to give you one; You'll be quite frustrated because you wouldn't know whether to look for another prof or wait longer for a response. Saying 'No' is fine and in fact a necessary part of professional life; but saying nothing is not acceptable. If you didn't reply, the sender will not even know whether you received the email.
Do not expect your tutor to code or debug for you. We strongly discourage tutors from giving technical help directly to their own teams because we want to train you in troubleshooting tech problems yourselves. Allowing direct tech help from tutors transfers the troubleshooting responsibility to tutors.
It is ok to ask for help from classmates even for assignments, even from other teams, as long as you don't copy from others and submit as your own. It doesn't matter who is helping you as long as you are learning from it.
We encourage you to give tech help to each other, but do it in a way that the other person learns from it.
Related: [Admin: Appendix D: Getting Help]
The source code are publicly available and are available for reuse by others without any restrictions.
Is publishing submissions unfair to the team? We don't think so. If you were the first to think of something your peers are willing
to adopt later, that means you are already ahead of them and they are unlikely to earn more marks by adopting your ideas.
We encourage sharing, but you should share with everyone in the class, not just a selected group. That is,
You can even reuse each other's work subject to the 'reuse policy' given below.
If you submit code (or adopt ideas) taken from elsewhere, you need to comply with our reuse policy.
Detection:
Penalties:
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 using 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.adoc (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//@@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 : (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 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.
Objective:
Sections to include:
Overview: A short overview of your product to provide some context to the reader.
Summary of Contributions:
https://nuscs2113-ay1819s1.github.io/dashboard/#=undefined&search=githbub_username_in_lower_case (replace githbub_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
Follow the example in the AddressBook-Level4, but ignore the following two lines in it.
- Minor enhancement: added a history command that allows the user to navigate to previous commands using up/down keys.
- Code contributed: [Functional code] [Test code] {give links to collated code files}
💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP.
Follow the example in the sample.
It is assumed that all contents in the PPP were written primarily by you. If any section is written
by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe).
Reason: Your writing skills will be evaluated based on the PPP
Page limit: If you have more content than the limit given below, shorten (or omit some content) so that you do not exceed the page limit. Having too much content in the PPP will be viewed unfavorably during grading. Note: the page limits given below 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.
| Content | Limit |
|---|---|
| Overview + Summary of contributions | 0.5-1 |
| Contributions to the User Guide | 1-3 |
| Contributions to the Developer Guide | 3-6 |
| Total | 5-10 |
In general, you are not allowed to involve outsiders in your project except your team members and the teaching team. However, It is OK to give your product to others for the purpose of getting voluntary user feedback. It is also OK to learn from others as long as they don't do your project work themselves.
We don't usually give a strict page limit for documents such as User Guide and the Developer Guide. You need to decide yourself how long the document should be based on the purpose and the intended audience. You can determine the level of details required based on the samples we provide.
What are the differences between the T and the non-T version of the module?
Why you force me to visit a separate website instead of using IVLE?
Why I’m not allowed to use my favorite tool/framework/language etc.?
Why submission requirements differ between CS2113/T and CS2101?
The Schedule pageSchedule page presents all you need to know in chronological order while the other pages have some of the same content organized by topic.
The Schedule pageSchedule page is the one page you need to refer weekly. Although there is a lot of content in the Admin Info page Admin Info page and the Textbook page -- which you are welcome to read in those respective pages -- the same content is also embedded in the relevant weeks of the Schedule page. Embedded extracts usually appear in expandable panels and can be identified by the symbol in the panel title.
Same lectures, same exam. Separate tutorials, separate project grading. Unless specified otherwise, whatever is stated for one module applies to the other.
CS2113/T prepares you for many higher-level project modules (CS3216/7, CS3203, CS3281/2, etc.), each requiring a slightly different skill set. It is also the only SE module some of you do before going for industry internships. Therefore, we have to cover many essential SE concepts/skills and also provide enough exercises for you to practice those skills. This is also why we don't have time to go very deep into any of the topics.
Remember, everything you learn here is going to be useful in a SE-related career.
Also, consider this a gradual introduction to 'heavy' modules; most project modules you do after this are going to be much heavier 😛
How to reduce the workload? You can omit Learning Outcomes rated . Furthermore, control the project workload by using no more than a fixed amount of time weekly on the project (e.g., 1 day).
In CS2113/T, A+ is not given simply based on the final score. To get an A+ you should,
Sometimes, small things matter in big ways. e.g., all other things being equal, a job may be offered to the candidate who has the neater looking CV although both have the same qualifications. This may be unfair, but that's how the world works. Students forget this harsh reality when they are in the protected environment of the school and tend to get sloppy with their work habits. That is why we reward all positive behavior, even small ones (e.g., following precise submission instructions, arriving on time etc.).
But unlike the real world, we are forgiving. That is why you can still earn full 10 marks of the participation marks even if you miss a few things here and there.
Related article: This Is The Personality Trait That Most Often Predicts Success (this is why we reward things like punctuality).
We have a separate website because some of the module information does not fit into the structure imposed by IVLE.
On a related note, keep in mind that 'hunting and gathering' of relevant information is one of the skills you need to survive 'in the wild'. Do not always expect all relevant materials to appear 'magically' in some kind of 'work bin'.
Slides are not meant to be documents to print and study for exams. Their purpose is to support the lecture delivery and keep you engaged during the lecture. That's why our slides are less detailed and more visual.
Self-study is a critical survival skill in SE industry. Lectures will show you the way, but absorbing content is to be done at your own pace, by yourself. In this module, we still tell you what content to study and also pass most of the content to you. After you graduate, you have to decide what to study and find your own content too.
If you do not have a laptop or prefer not to bring the laptop, it is up to you to show your work to the tutor in some way (e.g. by connecting to your home PC remotely), without requiring extra time/effort from the tutor or team members.
Reason: As you enjoy the benefits of not bring the laptop; you (not others) should bear the cost too.
Defining your own unique project is more fun.
But, wider scope → more diverse projects → harder for us to go deep into your project. The collective know-how we (i.e., students and the teaching team) have built up about SE issues related to the project become shallow and stretched too thinly. It also affects fairness of grading.
That is why a strictly-defined project is more suitable for a first course in SE that focuses on nuts-and-bolts of SE. After learning those fundamentals, in higher level project modules you can focus more on the creative side of software projects without being dragged down by nuts-and-bolts SE issues (because you already know how to deal with them). However, we would like to allow some room for creativity too. That is why we let you build products that are slight variations of a given theme.
Also note: The freedom to do 'anything' is not a necessary condition for creativity. Do not mistake being different for being creative. In fact, the more constrained you are, the more you need creativity to stand out.
"You tell me exactly what to do - I do that - you pay me (in grades)" is a model for contract work, not for learning. Being able to survive in imprecise, uncertain, volatile problem contexts is precisely what we are trying to teach you.
For example, the best way to communicate something often depends on what is being communicated. That is why we don't specify the precise content for project documents. Instead, we aim to refine project documents iteratively. We believe the learning experience will be richer if we let you decide the best way to present your project information rather than just following our instructions blindly. For example, in real-life projects you are rarely told which diagrams to draw; that is a decision you have to make yourself.
We have chosen a basic set of tools after considering ease of learning, availability, typical-ness, popularity, migration path to other tools, etc. There are many reasons for limiting your choices:
Pedagogical reasons:
Practical reasons:
Meanwhile, feel free to share with peers your experience of using other tools.
The high number of submissions is not meant to increase workload but to spread it across the semester. Learning theory and applying them should be done in parallel to maximize the learning effect. That can happen only if we spread theory and 'application of theory' (i.e., project work) evenly across the semester.
There are many reasons. One of them is that most of you will be working with existing software in your first few years of the career while hardly any school projects train you to work with existing code bases. We decided to bite the bullet and use CS2113/T to train you to work in existing code bases.
They do, and they should.
CS2113T communication requirements are limited to a very narrow scope (i.e., communicate about the product to users and developers). CS2101 aims to teach you technical communication in a much wider context. While you may be able to reuse some of the stuff across the two modules, submissions are not intended to be exactly the same.
This guide is mostly about getting tech help, but it also applies to getting clarifications on module topics too. e.g. what is the difference between refactoring and rewriting?
We want to move you away from 'hand holding' and make you learn how to solve problems on your own. This is a vital survival skill in the industry and it needs practice.
Whether it is a technical problem (e.g. error when using the IDE) or a doubt about a concept (e.g. what is the difference between scripted testing and exploratory testing?) the teaching team is happy to work with you when you look for a solution/answer, but we do not do it for you. We discourage unconditional direct help from tutors because we want you to learn to help yourself. Yes, we believe in ‘tough love’😝.
The question you should always ask yourself is, 'how do I solve this problem if the lecturer/tutors are not around to help me?'
What not to do:
What to do:
Check what is given: Check if the problem/concept has been discussed in the lectures, textbook, or the list of resources given to you. Yes, it is easier for you to write an email to the tutor/lecturer instead, but that shouldn't be your default behavior. We know that sometimes it is difficult to find stuff in the resources we have provided. But you should try first.
Search: It is very likely the answer already exists somewhere in the cyberspace. Almost every programming-related question has been answered in places like stackoverflow. Don't give
an opportunity for someone to ask you to STFW.
Pay attention to the error message you encounter. Sometimes it also contains hints as to how to fix the problem. Even if not, a web search on
the error message is a good starting point.
Ask peers:
Ask your team members.
Ask classmates using the module forum or the slack channel. Even if you figured out one way to solve a problem, discussing it on a public forum might lead you to better ways of solving it, and will help other classmates who are facing similar problems too. If you are really shy to ask questions in the forum, you may use this form to submit your question anonymously which we will then post in the forum.
Rubber duck debugging is an informal term used in software engineering to refer to a method of debugging code. The name is a reference to a story in the book The Pragmatic Programmer in which a programmer would carry around a rubber duck and debug his code by forcing himself to explain it, line-by-line, to the duck.
[for more, see wikipedia entry]
Ask the world using programming forums such as stackoverflow.
Here are some tips for posting help request:
PLEASE search for existing answers before you post your question in those public forums; You don't want to appear as a 'clueless' or 'too lazy to do your research' person in a public forum.
Learn to isolate the problem. "My code doesn't work" isn't going to help even if you post the whole code online. Others don't have time to go through all of your code. Isolate the part that doesn't work and strip it down to the bare minimum that is enough reproduce the error. Sometimes, this process actually helps you to figure out the problem yourself. If not, at least it increases the chance of someone else being able to help you.
💡 How to isolate problematic code? Delete code (one bit at a time) that is confirmed as not related to the problem. Do that until you can still reproduce the problem with the least amount of code remaining.
Generalize the problem. "How to write tasks to a text file using Java" is too specific to what you are working on. You are more likely to find help if you post a thread called (or search for) "How to write to a file using Java".
Explain well. Conversations via online forums take time. If you post everything that is relevant to your problem, your chances of getting an answer in the first try is higher. If others have to ask you more questions before they can help you, it will take longer. But this doesn't mean you dump too much information into the thread either.
💡 Know what these stand for: RTFM, STFW, GIYF
Talk to the lecturer before or after the lecture. The lecturer will be at the lecture venue from 30 minutes before the start of the lecture.
Request our help: Failing all above, you can always request for help by emailing the lecturer.
Resources
Create a personal GitHub account if you don't have one yet.
You are advised to choose a sensible GitHub username as you are likely to use it for years to come in professional contexts.
Strongly recommended: Complete your GitHub profile. In particular,
The GitHub profile is useful for the tutors and classmates to identify you. If you are reluctant to share your info in your long-term GitHub account, you can remove those details after the module is over or create a separate GitHub account just for the module.
We use various tools to analyze your code. For us to be able to identify your commits, you should use the GitHub username as your Git username as well. If there is a mismatch, or if you use multiple user names for Git, our tools might miss some of your work and as a result you might not get credit for some of your work.
In each Computer you use for coding, after installing Git, you should set the Git username as follows.
git config --global user.name YOUR_GITHUB_USERNAMEgit config --global user.name JohnDoeMore info about setting Git username is here.
Fork the repo to your personal GitHub account, if you haven't done so already.
Create a branch named after the LO IDe.g. W2.2b
Remember to switch to master branch before creating the new branch.
Commit your changes to that branch. Push to your fork.
Create a Pull Request against the master branch of the repo
https://github.com/nusCS2113-AY1819S1/{repo_name}
e.g. https://github.com/nusCS2113-AY1819S1/addressbook-level1
(do not create PRs against the upstream repo at se-edu org)
PR name should be: [LO_ID][TEAM_ID]Your Name
e.g. If you are in team 1 of tutorial W09 (i.e. Wednesday 9am), [W2.2b][W09-A1]James Yong.
Your Team ID can be found in this page. Note that our tutorial
IDs are different from those shown in CORS/IVLE. Our tutorial IDs are given in the panel below.
Relevant: [
Our tutorials start on week 2 (even before CORS tutorial bidding is over), not in week 3 as other modules do. CS2113 (not CS2113T) students need to choose a temporary tutorial slot for week 2 tutorial. We'll inform you the procedure to do so in due course.
Our tutorial IDs are different from CORS. Format: W12 means Wednesday 1200 and so on.
| Module | Tutorial ID (ID in CORS) | Time | Venue | Tutors (contact details) |
|---|---|---|---|---|
| CS2113T | W12 (1) | Wed 1200 | COM1-B103 | TBD |
| CS2113T | W13 (2) | Wed 1300 | COM1-B103 | TBD |
| CS2113T | T09 (3) | Thu 0900 | COM1-B103 | TBD |
| CS2113T | T12 (4) | Thu 1200 | COM1-B103 | TBD |
| CS2113T | F09 (5) | Fri 0900 | COM1-B103 | TBD |
| CS2113T | F10 (6) | Fri 1000 | COM1-B103 | TBD |
| CS2113 | T13 (1) | Thu 1300 | COM1-B103 | TBD |
| CS2113 | T16 (2) | Thu 1600 | COM1-B103 | TBD |
Check the 'Files Changed' tab on GitHub to confirm the PR contains intended changes only.
If the content of the PR is not as you expected, you can fix those problems in your local repo, commit, and push those new commits to the fork. The PR content will update automatically to match new commits. Alternatively, you can close that PR and create a new one with the correct content.
If your PR adapted/referred code from elsewhere (e.g. a stackoverflow post or a classmate's PR -- which is allowed, even encouraged), acknowledge the source in your PR description text. e.g. Some code adapted from #2431 (I followed the same technique for parsing user command)
If the PR is not ready for review yet, add a comment Work in progress. When the PR is ready for review later, add a comment Ready for review If there is no comment, we assume the PR is ready for review.
The instructions below are for setting up a GitHub organization for your team.
You can create your GitHub account after receiving your team ID. Here are the instructions (please follow the organization/repo name format closely because we use scripts to download your code. If the names are not as expected, our scripts will not work):
CS2113-AY1819S1-TEAM_ID. e.g. CS2113-AY1819S1-W12-1developers to your organization.Only one team member:
main. This repo is to be used as the repo for your project.All team members:
main repo (created above) to your personal GitHub account.Note that some of our download scripts depend on the following folder paths. Please do not alter those paths in your project.
/src/main/src/test/docsWhen you create a repo, you get an issue tracker for that repo automatically. Configure it as follows:
Issue type labels:
type.epic : A big feature which can be broken down into smaller stories e.g. searchtype.story : A user storytype.enhancement: An enhancement to an existing storytype.task : Something that needs to be done, but not a story, bug, or an epic. e.g. Move testing code into a new folder)type.bug : A bugStatus labels:
status.ongoing : The issue is currently being worked on. note: remove this label before closing an issue.
Priority labels:
priority.high : Must dopriority.medium : Nice to havepriority.low : Unlikely to doBug Severity labels:
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.Create following milestones : v1.0, v1.1, v1.2, v1.3, v1.4,
You may configure other project settings as you wish. e.g. more labels, more milestones
In general, use the issue tracker (Milestones, Issues, PRs, Tags, Releases, and Labels) for assigning, scheduling, and tracking all noteworthy project tasks, including user stories. Update the issue tracker regularly to reflect the current status of the project. You can also use GitHub's new Projects feature to manage the project, but keep it linked to the issue tracker as much as you can.
Record each of the user stories you plan to deliver as an issue in the issue tracker.
e.g. Title: As a user I can add a deadline
Description: ... so that I can keep track of my deadlines
Assign the type.* and priority.* labels to those issues.
When you start implementing a story, break it down to tasks. Define reasonable sized, standalone tasks. A task should be able to done by one person, in a few hours. e.g.
Write a descriptive title for the issue. e.g. Add support for the 'undo' command to the parser.
There is no need to break things into VERY small tasks. Keep them as big as possible, but they should be no bigger than what you are going to assign a single person to do within a week. eg.,
Implementing parser : too big because it cannot be done by a single person in a week.Implementing parser support for adding of floating tasks : appropriate size.Do not track things taken for granted. e.g., push code to repo should not be a task to track. In the example given under the previous point, it is taken for granted that the owner will also (a) test the code and (b) push to the repo when it is ready. Those two need not be tracked as separate tasks.
Omit redundant details. In some cases, the summary/title is enough to describe the task. In that case, no need to repeat it in the description. There is no need for well-crafted and detailed descriptions for tasks. A minimal
description is enough. Similarly, labels such as priority can be omitted if you think they don't help you.
Assign tasks to team members using the assignees field. At any point, there should be some ongoing tasks and some pending tasks against each team member.
Optionally, you can use status.ongoing label to indicate issues currently ongoing.
Use GitHub milestones to indicate which issues are to be handled for which milestone by assigning issues to suitable milestones.
Set the deadlines for milestones (in GitHub). Your internal milestones can be set earlier than the deadlines we have set, to give you a buffer.
Note that you can change the milestone plan along the way as necessary.
Wrapping up a Milestone:
Here are the conditions to satisfy for a milestone to be considered properly wrapped up:
A working product tagged with the correct tag (e.g. v1.2) is pushed to the main repo.
All tests passing on Travis for the version tagged above.
Milestone updated to match the product i.e. all issues completed and PRs merged for the milestone should be assigned to the milestone.
Milestone closed. If there are incomplete issues or unmerged PRs in the milestone, move them to a future milestone.
Optionally, issues for the next milestone are assigned to team members (this is not compulsory to do before the tutorial, but we recommend you to do it soon after the tutorial).
Optionally, future milestones are revised based on what you experienced in the current milestone e.g. if you could not finish all issues assigned to the current milestone, it is a sign that you overestimated how much you can do in a week, which means you might want to reduce the issues assigned to future milestones to match that observation.
Doing a 'release' on GitHub is optional for v1.1 and v1.2 but compulsory from v1.3.
We recommend using the Forking Workflow.
If your team is facing difficulties due to differences in skill/motivation /availability among team members,
First, do not expect everyone to have the same skill/motivation level as you. It is fine if someone wants to do less and have low expectations from the module. That doesn't mean that person is a bad person. Everyone is entitled to have their own priorities.
Second, don't give up. It is unfortunate that your team ended up in this situation, but you can turn it into a good learning opportunity. You don't get an opportunity to save a sinking team every day 😃
Third, if you care about your grade and willing to work for it, you need to take initiative to turn the situation around or else the whole team is going to suffer. Don't hesitate to take charge if the situation calls for it. By doing so, you'll be doing a favor for your team. Be professional, kind, and courteous to the team members, but also be firm and assertive. It is your grade that is at stake. Don't worry about making a bad situation worse. You won't know until you try.
Finally, don't feel angry or 'wronged'. Teamwork problems are not uncommon in this module and we know how to grade so that you will not be penalized for others' low contribution. We can use Git to find exactly what others did. It's not your responsibility to get others to contribute.
Given below are some suggestions you can adopt if the project work is not going smooth due to team issues. Note that the below measures can result in some team members doing more work than others and earning better project grades than others. It is still better than sinking the whole team together.
Redistribute the work: Stronger programmers in the team should take over the critical parts of the code.
Enforce stricter integration workflow: Appoint an integrator (typically, the strongest programmer). His/her job is to maintain the integrated version of the code. He/she should not accept any code that breaks the existing product or is not up to the acceptable quality standard. It is up to others to submit acceptable code to the integrator. Note that if the integrator rejected your code unreasonably, you can still earn marks for that code. You are allowed to submit such 'rejected' code for grading. They can earn marks based on the quality of the code.
If you have very unreliable or totally disengaged team members :