This module is organized primarily around a list of Learning Outcomes.

Each week has a suggested list of LOs. They are categorized using the following star-rating system:

Timing/venue: Fri 1400-1600 ICube Auditorium. Lectures start at 1400 sharp and end around 1545 (15 minutes to travel to next lecture).

Each lecture consists of two sections:

• First half: Flipped classroom format. Discusses the learning outcomes of the current week.
• Second half: A preview of the learning outcomes for the following week.

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 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.

Our tutorials start on week 2 (even before CORS tutorial bidding is over), not in week 3 as other modules do. CS2103 (not CS2103T) students need to choose a temporary tutorial slot for week 2 tutorial. We'll inform you the procedure to do so in due course.

What happens during the tutorial:

• A tutorial group is handled by two tutors. Each tutor will work with two teams.
• The tutor will direct students to share/discuss evidence of achieving the weekly learning outcomes (LO).
• If some students have met with difficulties while achieving an LO, the tutor can direct those students to get help from those who have achieved the LO. The number of LOs that can be covered in the tutorial session depends on how well-prepared you are.
• The tutor will observe, and give feedback on, how well you are achieving required LOs.
• Please bring your laptop to tutorials. You often need it to show evidence of LOs you achieved. At other times, we ask you to work on project related things with your team members, which too may require the laptop.

The role of our tutors is different from tutors in other modules.

• No direct tech help: Tutors are prohibited from giving technical help. Rationale: We want you to learn the vital survival skill of troubleshooting technical problems.

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?)we the teaching team are 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?'

Note: 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?

What not to do:

When faced with a technical problem or a doubt about a concept, don'f fire off an email lecturer/tutor immediately after you encounter a problem or a doubt, unless it is something only the lecturer/tutor is supposed to know. Instead, here are some things you can do:

• Check what is given: Check if the problem/concept has been discussed in the lectures, text book, 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

• [lifehacker article]  Google Tips and Tricks Every Student Should Know
• [Article] How To Ask Questions The Smart Way by Eric Steven Raymond

• No ‘teaching’: Tutors are prohibited from “teaching” concepts that are covered in lectures or other learning resources given to you. Self-learning is a vital part of the module. But tutors may help you clarify doubts.

• No leading from the front: Tutors are not expected to lead your project effort. They will not tell you how to do project tasks or when to do project tasks. You have to figure those out yourselves. But tutors will give you feedback on how you are doing (or have done) project tasks so that you can improve further.

Timing/venue:

• Please refer to the Schedule page for further details on each tutorial.
• You are expected to arrive on time. Punctuality is considered for participation marks.
• You may leave the class 15 minutes before the hour if you have another class right after. There is no need to wait till the tutor dismisses you. However, inform the tutor (as a courtesy) before leaving if you leave before the class is dismissed.
• Please make sure you vacate the table 5 minutes before the hour so that the next group can start on time.
• In the past many students have suggested to increase the tutorial duration because 1 hour is barely enough to get through all weekly LOs. Increasing the tutorial time is not possible due to lack of venues and tutors. Instead, let's try to make the best of the one hour available by coming well prepared and starting on time.

Grading:

Tutorials are not graded. However, your conduct will be reviewed by team members and the tutor which will determine your participation marks.

The main text book is here. While it is in a dynamic Web page format, there is a way to save the main text as pdf files.

The high-level learning outcome of the project (and to a large degree, the entire module):

🏆 Can contribute production quality SE work to a small/medium software project

Accordingly, the module project is structured to resemble an intermediate stage of a non-trivial real-life software project. In this project you will,

1. conceptualize and implement enhancements to a given product,
2. and have it ready to be continued by future developers.

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.

Your project should comply with the following constraints. Reason: to increase comparability among submissions and to maximize applicability of module content 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 (week 6-13). 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. Use of relational or No-SQL databases are not allowed.
  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 OOP that you learned in the course.

• Constraint-Windows: The software should work on the Windows platform.
  Reason: Final testing will be done on Windows machines.

• Constraint-No-Installer: The software should work without requiring an installer. Having an optional installer is OK as longs 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,

  • are free.
  • do not require any installation by the user of your software.
  • do not violate other constraints.

  and is subjected to prior approval by us.
  Reason: We will not allow third-party software that can interfere with the learning objectives of the module.

  Please post your request for approval in IVLE forum before you start using the library.
  Reason: The whole class should know which external software are used by others so that they can do the same if they wish to.

To expedite your project implementation, you will be given some sample code (AddressBook-Level1 to AddressBook-Level4, shown as AB-1 to AB-4 in the diagram above) that you can use as the basis for improving your individual skills during Phases A and as the basis for your project in Phase B.

AB-4 is the version you will use as the starting point for your final project. Some of the work you do in AB-1 to AB-3 can be ported over to AB-4 and can be used to claim credit in the final project.

The sub-sections further down explain each project deliverable in detail.

v1.2 Project Management

As before, you are recommended (but not required) to follow the forking workflow when evolving the product.

From v1.2 onwards each member is expected to contribute some code to each weekly milestone; only merged code is considered as contributions (Reason) . If you miss more than two weekly milestones, you will start losing marks.
If an enhancement is too big to complete in one week, here are some options:

• [Preferred] Deliver it in smaller incremental steps e.g. deliver a basic version of the enhancement first.
• Do a different, smaller, enhancement for the current week while working on a bigger enhancement to deliver in a future week.
• Choose not contribute to the weekly milestone. This should be fine as long as you don't miss more than two milestones.

v1.2 Product

Submission: Update code in GitHub.

Grading: Criteria to consider this milestone as reached

• A new version tagged v1.2 is in your repo.  If v1.2 is already used by a past commit, you can use something similar such as V1.2 or v1.2.0.
• The version v1.2 is step towards v2.0 (but it does not matter how big a step it is)

v1.2 Documentation

• User Guide: Update as necessary.

  • If a feature has been released in this version, replace the Coming in v2.0 annotation with a Since v1.2. Also replace UI mockups with actual screenshots.
  • If a feature design has changed, update the descriptions accordingly.

• Developer Guide:

  • Each member should describe the implementation of at least one enhancement she has added (or planning to add).
    Expected length: ~1 page per person
  • The description can contain things such as,
    • How the feature is implemented.
    • Why it is implemented that way.
    • Alternatives considered.
  • The stated objective is to explain the implementation to a future developer, but a hidden objective is to show evidence that you can document deeply-technical content using prose, examples, diagrams, code snippets, etc. appropriately. To that end, you may also describe features that you plan to implement in the future, even beyond v1.5 (hypothetically).
  • For an example, see the description of the undo/redo feature implementation in the AddressBook-Level4 developer guide.

v1.2 Demo

Do an informal demo of the new feature during the tutorial. Each team member should demo their own work, using the master branch.

v1.3 Project Management

As before, the milestone v1.3 must be wrapped up on GitHub. Remember to move all incomplete issues to a future milestone and close the milestone so that it no longer appears under open milestones.

v1.3 Product

Submission: Do a release on GitHub

Grading:

Criteria to consider this milestone as reached:

• The new version has moved towards v2.0 compared to the previous version.
• The milestone is wrapped up and the release has been done.

v1.3 Documentation

• User Guide: Update where the document does not match the current product.
• Developer Guide: Similar to User Guide.

Submission: Must be included in the version tagged v1.3.

Grading: To consider this milestone as reached, your documentation should not be noticeably behind the product.

v1.3 Demo

Do an informal demo of the new features during the tutorial. Each person should demo their own contributions.

v1.4 Project Management

v1.4 Product

As before, move the product towards v2.0.

Submission: Push the code (including the collated folder and files created above) to GitHub.

Grading criteria:

• Code collated properly
• Criteria given in v1.3

v1.4 Documentation

• 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,

  • Describe the profile of the target user
  • Remove irrelevant content such as Learning Outcomes
  • Update the Ui.png to match the current product

• User Guide: This document will be used by acceptance testers. Update to match the current version. In particular,

  • Clearly indicate which features are not implemented yet  e.g. tag those features with a Coming in v2.0.
  • For those features already implemented, ensure their description match the exact behavior of the product  e.g. replace mockups with actual screenshots

• 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.4.

v1.4 Demo

As before.

v1.4 Acceptance Testing

Objectives:

• To train you to do manual testing, bug reporting, bug triaging, bug fixing, communicating with users, evaluating products etc. (Note: you will be doing a graded acceptance testing session in week 13; this session will serve as practice for that)
• To help you improve your product before the final submission.

When, where:

• To be done during Lecture 11. Duration: 30 minutes.

During the session:

• Each student will be assigned a product from another team to test.
• Download the latest jar file from the team's GitHub page. Copy it to an empty folder.
• Test the product based on the user guide. First, acceptance test it from the perspective of the target user profile. If there is any time left, you can switch to system testing mode.
• Post bugs you find in the team's issue tracker.
  • Each bug should be a separate issue.
  • Even problems in the user guide  e.g. lack of explanations can be posted as issues.
  • Feel free to post other suggestions for improvements too  e.g. ways to improve the command format.
• Do not use the session time to read bug reports your team is receiving.
• Before posting a report/suggestion, check if it is already posted by someone else. If it is, post in the same thread to confirm/support the issue and add your input.
• Use descriptive titles for the issues. Give a good description of the bug/suggestion, including steps required to reproduce.

Grading:

• Attendance is strongly encouraged but not compulsory. Your participation in the session benefits your team because the number of testers testing your product will depend on how many members of your team is taking part in testing  e.g. if 3 members of your team are taking part in testing, three other testers will be assigned to test your product.
• There is no penalty for bugs reported at this session.
• The reward for reporting bugs or suggesting features: do include it in your project portfolio page to show how you contributed to another project.

After the session:

• It is up to you to decide whether you will act on those issues before the final submission v1.5. For some issues, the correct decision could be to reject or postpone.
• You can post in the issue thread to communicate with the tester  e.g. to ask for more info, etc. However, the tester is not obliged to respond.

rc = Release Candidate

v1.5rc Project Management

We strongly recommend you to freeze features after reaching this milestone. As this is a release candidate, it should have all the features you intend to release at v1.5. Adding more features after this point is risky. The remaining time should be left aside for fixing problems discovered late.

v1.5rc Product

• As before, you can continue to add more enhancements.
• Also, consider increasing code coverage by adding more tests if it is lower than the level you would like it to be. Take note of our expectation on test code.
• After you have sufficient code coverage, fix remaining code quality problems and bring up the quality to your target level.

Code Quality

Introduction

Basic

🏆 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}

Production code needs to be of high quality. Given how the world is becoming increasingly dependent of software, poor quality code is something we cannot afford to tolerate.

Code being used in an actual product with actual users

Guideline: Maximise Readability

Introduction

🏆 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.

Example: The two code samples given below achieve the same functionality, but one is easier to read.

int subsidy() {
    int subsidy;
    if (!age) {
        if (!sub) {
            if (!notFullTime) {
                subsidy = 500;
            } else {
                subsidy = 250;
            }
        } else {
            subsidy = 250;
        }
    } else {
        subsidy = -1;
    }
    return subsidy;
}

int calculateSubsidy() {
    int subsidy;
    if (isSenior) {
        subsidy = REJECT_SENIOR;
    } else if (isAlreadySubsidised) {
        subsidy = SUBSIDISED_SUBSIDY;
    } else if (isPartTime) {
        subsidy = FULLTIME_SUBSIDY * RATIO;
    } else {
        subsidy = FULLTIME_SUBSIDY;
    }
    return subsidy;
}

Basic

🏆 Can follow basic guidelines for improving readability

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.

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:

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:

return ((length < MAX_LENGTH) || (previousSize != length)) && (typeCode == URGENT);

boolean isWithinSizeLimit = length < MAX_LENGTH;
boolean isSameSize = previousSize != length;
boolean isValidCode = isWithinSizeLimit || isSameSize;

boolean isUrgent = typeCode == URGENT;

return isValidCode && isUrgent;

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}

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”).

Example:

return 3.14236;	return PI
return 9	return MAX_SIZE-1

Using a named constant makes the code easier to understand because the name tells us more about the meaning of the number. Similarly, we can have ‘magic’ values of other data types.

return “Error 1432”;  // A magic string!

Make the code as explicit as possible, even if the language syntax allows them to be implicit. Here are some examples:

• Use explicit type conversion instead of implicit type conversion.
• Use parentheses/braces to show grouping even when they can be skipped.
• Use enumerations when a certain variable can take only a small number of finite values. For example, instead of declaring the variable 'state' as an integer and using values 0,1,2 to denote the states 'starting', 'enabled', and 'disabled' respectively, declare 'state' as type SystemState and define an enumeration SystemState that has values 'STARTING', 'ENABLED', and 'DISABLED'.
• When statements should follow a particular order, try to make it obvious (with appropriate naming, or at least comments). For example, if you name two functions 'taskA()' and 'taskB()', it is not obvious which one should be called first. Contrast this with naming the functions 'phaseOne()' and 'phaseTwo()' instead. This is especially important when statements in one function must be called before the other one.

Intermediate

🏆 Can follow intermediate guidelines for improving readability

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.

Avoid things that would make the reader go ‘huh?’, such as,

• unused parameters in the method signature
• similar things look different
• different things that look similar
• multiple statements in the same line
• data flow anomalies such as, pre-assigning values to variables and modifying it without any use of the pre-assigned value

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}

Optimizing code prematurely has several drawbacks:

• We may not know which parts are the real performance bottlenecks. This is especially the case when the code undergoes transformations (e.g. compiling, minifying, transpiling, etc.) before it becomes an executable. Ideally, you should use a profiler tool to identify the actual bottlenecks of the code first, and optimize only those parts.
• Optimizing can complicate the code, affecting correctness and understandability
• Hand-optimized code can be harder for the compiler to optimize (the simpler the code, the easier for the compiler to optimize it). In many cases a compiler can do a better job of optimizing the runtime code if you don't get in the way by trying to hand-optimize the source code.

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 thingse.g. when writing code for resource-constrained environments. This guideline simply a caution that you should optimize only when it is really needed.

Avoid varying the level of abstraction within a code fragment. Note: The Productive Programmer (by Neal Ford) calls this the SLAP principle i.e. Single Level of Abstraction Per method.

Example:

readData();
salary = basic*rise+1000;
tax = (taxable?salary*0.07:0);
displayResult();

readData();
processData();
displayResult();

Design → Design Principles → Abstraction →

What

Abstraction: Abstraction is a technique for dealing with complexity. It works by establishing a level of complexity on which a person interacts with the system, suppressing the more complex details below the current level.

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.

For example,

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.

Putting all details in one place can create lengthy methods, but it is preferred over creating many small methods because it makes the code easier to understand.

• True
• False

False

Explanation: If you are using abstraction properly, you DON’T need to see all details to understand something. The whole point of using abstraction is to be able to understand things without knowing as little details as possible. This is why we recommend single level of abstraction per method and top-down coding.

What are the drawbacks of trying to optimize code too soon?

• a. We may not know which parts are the real performance bottleneck
• b. When we optimize code manually, it becomes harder for the compiler to optimize
• c. Optimizing can complicate code
• d. Optimizing can lead to more error-prone code

a, b, c, d

This is a common saying among programmers

• a. Make it fast, make it right, make it work
• b. Make it work, make it right, make it fast
• c. Make it fast, make it right, now make it faster

b

Advanced

🏆 Can follow advanced guidelines for improving readability

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:

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,

• Unusual condition detection is separated from their handling.
• Main path is nested deeply.

if (isUnusualCase) { //Guard Clause
    handleUnusualCase();
    return;
}

if (isErrorCase) { //Guard Clause
    handleError();
    return;
}

start();
process();
cleanup();
exit();

In contrast, the above code

• deals with unusual conditions as soon as they are detected so that the reader doesn't have to remember them for long.
• keeps the main path un-indented.

Guideline: Follow a Standard

Introduction

🏆 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?

• a. Each developer should find a suitable coding standard and follow it in their coding.
• b. A developer should understand the importance of following a coding standard. However, there is no need to follow one.
• c. A developer should find out the coding standards currently used by the project and follow that closely.
• d. Coding standards are lame. Real programmers develop their own individual styles.

c

What is the aim of using a coding standard? How does it help?

Basic

🏆 Can follow simple mechanical style rules

Go through the provided Java coding standard and learn the basic style rules.

Intermediate

🏆 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?

• a. integer variable name: totalPeople
• b. boolean variable name: checkWeight
• c. method name (returns integer): getPeopleCount
• d. method name (returns boolean): isValidAddress
• e. String variable name: description

b

Explanation: checkWeight is an action. Naming variables as actions makes the code harder to follow. isWeightValid may be a better name.

Guideline: Name Well

Introduction

🏆 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}

Basic

🏆 Can follow basic guidelines for naming

Use nouns for classes/variables and verbs for methods/functions.

Examples:

Name for a
Class	CheckLimit	LimitChecker
method	result()	calculate()

Distinguish clearly between single valued and multivalued variables.

Examples:

Person student
ArrayList<person> students

Use correct spelling in names. Avoid 'texting-style' spelling. Avoid foreign language words, slang, and names that are only meaningful within specific contexts/timese.g. terms from private jokes, a TV show currently popular in your country

Intermediate

🏆 Can follow intermediate guidelines for naming

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:

processInput() (what 'process'?)	removeWhiteSpaceFromInput()
flag	isValidInput
temp

If the name has multiple words, they should be in a sensible order.

Examples:

bySizeOrder()	orderBySize()

Imagine going to the doctor's and saying "My eye1 is swollen"! Don’t use numbers or case to distinguish names.

Examples:

value1, value2	value, Value	originalValue, finalValue

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.

Related things should be named similarly, while unrelated things should NOT.

Example: Consider these variables

• colorBlack : hex value for color black
• colorWhite : hex value for color white
• colorBlue : number of times blue is used
• hexForRed : : hex value for color red

This 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:

• hexForBlackhexForWhitehexForRed
• blueColorCount

Avoid 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:

		Reason
phase0	phaseZero	Is that zero or letter O?
rwrLgtDirn	rowerLegitDirection	Hard to pronounce
rightleftwrong	rightDirectionleftDirectionwrongResponse	right is for 'correct' or 'opposite of 'left'?
redBooksreadBooks	redColorBooksbooksRead	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

Guideline: Avoid Unsafe Shortcuts

Introduction

🏆 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.

Basic

🏆 Can follow basic guidelines for avoiding unsafe shortcuts

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.

if (red) print "red";
else print "blue";

if (red) print "red";
else if (blue) print "blue";
else error("incorrect input");

• Use one variable for one purpose. Do not reuse a variable for a different purpose other than its intended one, just because the data type is the same.
• Do not reuse formal parameters as local variables inside the method.

double computeRectangleArea(double length, double width) {
    length = length * width;
    return length;
}

double computeRectangleArea(double length, double width) {
    double area;
    area = length * width;
    return area;
}

Never write an empty catch statement. At least give a comment to explain why the catch block is left empty.

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.

Which of these are unsafe coding practices?

• a. case statements without a default clause

• b. Omitting braces when a code block has only one statement

  e.g writing this

  if(isProper)
      return PROPER_AMOUNT;
  

  instead of

  if(isProper){
      return PROPER_AMOUNT;
  }
  

• c. Using a variable just to explain what’s going on

  e.g.writing this

  boolean isProper = notNull && notEmpty;
  return isProper;
  

  instead of

  return notNull && notEmpty;
  

a, b.

Reason why [c] is not a bad practice: The extra variable helps to make the code more understandable because it makes the intent of the formula clearer.

Intermediate

🏆 Can follow intermediate guidelines for avoiding unsafe shortcuts

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:

• Refactoring: Reduce Scope of Variable

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 DRY Principle .

Supplmentary → Principles →

DRY Principle

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.

Guideline: Comment Minimally, but Sufficiently

Introduction

🏆 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.

Basic

🏆 Can follow basic guidelines for writing code comments

If the code is self-explanatory, refrain from repeating the description in a comment just for the sake of 'good documentation'.

// increment x
x++;

//trim the input
trimInput();

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.

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(){
    ....
}

/** Trims the input of leading and trailing spaces */
void trimInput(){
    ....
}

Intermediate

🏆 Can follow intermediate guidelines for writing code comments

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:

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);

Reason: Code refactored to be self-explanatory. Comment no longer needed.

boolean isSameSize = (input.size() == size) ;
return (isLeftEndCorrect && isRightEndCorrect) || isSameSize;

In general, comments should describe,

• a. WHAT the code does
• b. WHY the code does something
• c. HOW the code does something

a, b

Explanation: How the code does something should be apparent from the code itself. However, comments can help the reader in describing WHAT and WHY aspects of the code.

Submission: as before.

Grading: as before.

v1.5rc Documentation

Update to match the product.

Submission: Must be included in the version tagged v1.5rc.

v1.5rc Demo

• Objective: to serve as a rehearsal for the final project demo at v1.5
• Duration: ~3 minutes (max) per person   a 4-member team will have 12 minutes
• Organize the demo to present a cohesive picture of the product as a whole. Unlike in v1.2-v1.4 demos, there is no need for each person to demo their own features.
• Cover all features, not just the ones added in the recent iteration.
• It should be a 'well prepared' demo. You should know in advance exactly what you'll do in the demo.
• It is a sitting down demo: You'll be demonstrating the features using the TV while sitting down.
• It will be uninterrupted demo: The tutor will not interrupt you during the demo. That means you should finish within the given time.
• The app should be populated with a significant amount of realistic data at the start. e.g at least 20 contacts.

v1.5 Product

This is as a ‘production release’. It should be at least ‘near production quality’.

Add these two new files to the repo (these will be used by our testers when testing your final submission):

• {project root}\src\test\data\ManualTesting\[team][Project Name]SampleData.xml : e.g. [T09-B1][ContactsPlus]SampleData.xml Sample data that can be loaded to your app. Should contain 20+ items.
• {project root}\src\test\data\ManualTesting\[team][Project Name]TestScript.adoc : e.g. [T09-B1][ContactsPlus]TestScript.adoc A document explaining the steps to perform manual testing (i.e. manual scripted testing), starting with how to load the sample data.
  Should cover all functionality of the product. Should be grouped by functionality.
  Should specify the command to type and the expected result (screenshots not required).
  Limit the test cases to about 20 minutes worth of testing.

Submission:

• Source code: Push the code to GitHub and tag with the version number. Source code (including collated .md files; please ensure the collated .md files are up to date; any updates to collated code files after the deadline comes with an automatic penalty) Note that the quality of the code in these collated code files accounts for a significant component of your final score, graded individually.
• Executable: upload the jar file to IVLE. File name: [team][product name].jare.g. [T09-B1][ContactsPlus].jar
• Test data/instructions: Upload following files to IVLE.
  • Sample data file. File name [team][Project Name]SampleData.xmle.g. [T09-B1][ContactsPlus]SampleData.xml
  • Testing instructions. File name [team][Project Name]TestScript.pdfe.g. [T09-B1][ContactsPlus]TestScript.pdf

Deadline: Week 13 Monday 23.59.

Grading:

v1.5 Documentation

Submission:

First, update following pages on GitHub:

• User Guide, Developer Guide
• README : Ensure the Ui.png matches the current product
• AboutUs : Ensure the following:
  • Contains a link to each person's Project Portfolio page
  • Team member names match full names used by IVLE

Next, convert the following documents to pdf (AB4 dev guide has some instructions on converting project docs to pdf) and upload to IVLE.

Deadline: Same as v1.5 product.

Grading:

v1.5 Demo

• Venue: Same as the tutorial venue unless informed otherwise.
• Duration: Strictly teamSize x 3 minutes  e.g. 12 minutes for a 4-person team. Exceeding this limit will be penalized.
• Schedule: Your demo timing is same as your tutorial time in week 13.
  Starting times: Team B1: 00 minutes, B2: 15 minutes, B3: 30 minutes, B4: 45 minutes
  At least some team members need to arrive 15 minutes ahead of the allocated time to set up your computer.
  There is an automatic penalty if you are not ready to start on time.
  Wait outside the venue until you are called in.
• 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.
• Scope:
  • Organize the demo to present a cohesive picture of the product as a whole, similar to the v1.5rc demo.
  • Remember to explain the profile of the target user early in the demo.
  • The scenarios you demonstrate should be chosen judiciously so that you cover the full range of your product's functionality. Give more time to stronger features (i.e. cover mundane/basic features fast). It is recommended you showcase how the product improves the user’s life rather than simply describe each feature.
  • No need to cover design/implementation details as the manager is not interested in those details.
• Dress code : The level of formality is up to you, but it is recommended that the whole team dress at the same level.
• Structure:
  Demo the product using the same executable you submitted, on your own laptop, using the TV.
  Every team member should take part in the demo. However, it's ok for one member to do all the typing.
• Optimizing the time:
  Try to make the maximum use of the short demo time in the following ways,
  • Spend as much time as possible on demonstrating the actual product. Not recommended to use slides (if you do, use them sparingly) or videos or lengthy narrations.
    Avoid skits, re-enactments, dramatizations etc. This is not a sales pitch or an informercial. While you need to show how a user use the product to get value, but you don’t need to act like an imaginary user. For example, [Instead of this]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.
    Note that CS2101 demo requirements may differ. Different context → Different requirements.
  • Rehearse the steps well and ensure you can do a smooth demo. Demos that are clearly under-prepared will be penalized.
  • Don’t waste time repeating things the target audience already knows. e.g. no need to say things like "We are students from NUS, SoC".
  • No need to spend time describing features that existed in original AB4 but you can mention if you did any changes to those features.
  • Bring sufficient amount of sample data and know how to load them to the system. You should not plan to type all the sample data during the demo itself. On the other hand, trying to demo a product using just 1-2 sample data creates a bad impression too.
  • Plan the demo to be in sync with the impression you want to create. For example, if you are trying to convince that the product is easy to use, show the easiest way to perform a task before you show the full command with all the bells and whistles.
  • Limit the demo to CLI inputs only. There is no point explaining GUI inputs because they don't earn marks.

Grading:

Note that project grading is not competitive (not bell curved). CS2103T projects will be assessed separately from CS2103 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)

The tutor's main job is to observe, facilitate self/peer learning, evaluate, and give feedback.

Tutorial time is the main avenue for meeting your tutor. In addition, you can meet the tutor 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 tutor’s job to chase you down and give help. It is up to you to get as much feedback from the as you need. You are free to request more feedback from the tutor as necessary. Similarly, it is not the job of the project supervisor to lead your project to success.

Your Phase B tutor will also be your project supervisor.

[Picture: The team that was at the top of early Google]

The two teams:
You will be in two different teams at different times of the semester.

• Weeks 1 - 5: Phase A team
• Weeks 6 - 13: Phase B team (i.e. Project team)

Phase A (Weeks 1 - 5) is the period for strengthening individual competencies. By working with different classmates during this period you get to know and learn from more classmates. The project is done in Phase B. That means your Phase B team is also your project team.

There cannot be any overlap between your 2 teams. For example, any member from your Phase A team cannot be a member of your Phase B team.

When to form teams

• CS2103T: Your Phase A team will be formed by CS2101 side in week 1. Your Phase B team (applicable to CS2101 too) will be formed by CS2103T side on week 5.
• CS2103: Form tentative Phase A teams in week 2 (during the tutorial). Finalize Phase A team in the subsequent tutorial. Form Phase B team on week 5.

Team size: The default team size is four.

Team ID: This will be given to you after forming teams in each Phase . It has the form TUTORIAL_ID-PHASE+TEAM_NUMBER e.g, W14-A2 means you are in tutorial W14 (i.e., Wed 1400-1500), Phase A, team 2.

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 allowedRationale: 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.

• 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.

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]

• ❗️ Submitting peer evaluations is compulsory. If you routinely miss submitting peer evaluations, you forfeit your participation marks.
• 💡 TEAMMATES normally allows students to access it without using Google login. In this module, we encourage you to login to TEAMMATES using your Google account and complete your profile with a suitable profile photo.  Reason:CS2103 is a big class. This profile helps us to remember you better, even after the module is over.

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. Some examples can be seen in the 'Teaching team' page. Given below are some examples of good and bad profile photos.

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. 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.

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.

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.

There is no midterm.

The final exam has two parts:

• Part 1: MCQ questions (1 hour, 24 marks)
• Part 2: Essay questions (1 hour, 16 marks)

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 1 hour 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.

Final Exam: Part 1 (MCQ)

Each MCQ question gives you a statement to evaluate.

Unless stated otherwise, the meaning of answer options are
A.Agree with confidence
B.Agree, but not confident
C.Question unclear (in this case, write down your doubt in the question paper)
D.Disagree, but not confident
E.Disagree with confidence

Incorrect answers receive negative marks. Here is an example marking scheme for a question that gives you a correct statement.  The scheme will be reversed if the statement given is incorrect.

A. Agree with confidence (+0.2)
B. Agree, but not confident (+0.1)
C. Question unclear (0)
D. Disagree, but not confident (-0.1)
E. Disagree with confidence (-0.2)

 Negative marks are necessary because all questions are Agree/Disagree type. Without negative marks, anyone can score roughly half the marks by simply choosing the same option for all questions.

All questions carry equal marks.

The exam paper has 133 questions.

• 3 are dummy questions used for admin purposes (not graded).
• The remaining 130 questions includes 10 extra questions. i.e., you need only 120 correct answers to get full marks.
  • These extra questions are meant as a safety buffer against mistakes you might commit under exam pressure or questions that are not clear to you.
  • Alternatively, you can simply skip (or use option C for) 10 questions.

Note that you have slightly less 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.

• If a question is not clear, you can choose option C and write your doubt in the exam paper, near the unclear question.
• If your doubt is justified (e.g. there is a typo in the question) or if many students found the question to be unclear, the examiner may decide to omit that question from grading.

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. As each OCR form can accommodate only 50 answers, you will be given three OCR forms. Indicate your student number in all three OCR forms.

To save space, we use the following notation in MCQ question. [x | y | z] means ‘x and z, but not y’

Some questions will use underlines or highlighting to draw your attention to a specific part of the question. That is because those parts are highly relevant to the answer and we don’t want you to miss the relevance of that part.

Markers such as the one given below appears at left margin of the paper to indicate where the question corresponds to a new column in the OCR form. E.g. questions 11, 21, 31, etc. (a column has 10 questions). Such markers can help you to detect if you missed a question in the previous 10 questions. You can safely ignore those markers if you are not interested in making use of that additional hint.

Some questions have tags e.g., the question below has a tag JAVA. These tags provide additional context about the question. In the example below, the tag indicates that the code given in the question is Java code.

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 130+ questions, 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.

Final Exam: Part 2 (Essay)

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.

[Sample paper] [ Answers to the sample paper]

To get the full marks allocated for participation you should satisfy the following criteria, evaluated based on peer evaluations and tutor observations. We will also take into account data recorded in other systems e.g. GitHub, IVLE.

• Professional Communication :

  • Communicates sufficiently and professionally. e.g. Does not use offensive language or excessive slang in project communications.
  • Responds to communication from team members in a timely manner (e.g. within 24 hours).

• Punctuality: Does not cause others to waste time or slow down project progress by frequent tardiness.

• Dependability: Promises what can be done, and delivers what was promised.

• Effort: Puts in sufficient effort to, and tries their best to, keep up with the module/project pace. Seeks help from others when necessary.

• Quality: Does not deliver work products that seem to be below the student's competence level i.e. tries their best to make the work product as high quality as possible within her competency level.

• Meticulousness:

  • Rarely overlooks submission requirements.
  • Rarely misses compulsory module activities such as completing the TEAMMATES profile or peer review.

• Teamwork: How willing are you to act as part of a team, contribute to team-level tasks, adhere to team decisions, etc.

The following criteria will be assessed but considered only for pushing a student's grade from A to A+ and recruiting future tutors/interns.

• Technical Competency: Able to gain competency in all the required tools and techniques.
• Mentoring skills: Helps others when possible. Able to mentor others well.
• Communication skills: Able to communicate (written and spoken) well. Takes initiative in discussions.

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,

• We may not take the most efficient route to building the software product. We take the route that allows you to learn the most.
• Building a software product that is unique, creative, and shiny is not our priority (although we try to do a bit of that too). Learning to take pride in, and discovering the joy of, high quality software engineering work is our priority.

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 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.

Policy on following instructions

Policy on grading smaller/larger teams

Policy on project work distribution

Policy on absence due to valid reasons (e.g. MC, LOA, University events)

Policy on email response time

Policy on tech help

Do not expect your project 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.

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?)we the teaching team are 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?'

Note: 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?

What not to do:

When faced with a technical problem or a doubt about a concept, don'f fire off an email lecturer/tutor immediately after you encounter a problem or a doubt, unless it is something only the lecturer/tutor is supposed to know. Instead, here are some things you can do:

• Check what is given: Check if the problem/concept has been discussed in the lectures, text book, 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

• [lifehacker article]  Google Tips and Tricks Every Student Should Know
• [Article] How To Ask Questions The Smart Way by Eric Steven Raymond

Policy on publishing submissions

Policy on plagiarism

Policy on reuse

Policy on help from outsiders

Policy on suggested length for submissions

Where is everything?

What are the differences between CS2103 and CS2103T?

Why the workload is so high?

CS2103/T prepares you for many higher-level project modules (CS3216/7, CS3201/2, CS3281/2, CG3002, etc.), each requiring a slightly different skill set. It is also the only SE course 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 ⭐️⭐️⭐️⭐️ They are counted for CS2103R and for A+ grades only.

How do I get CS2103R credit for optional LOs?

What are the extra requirements to get an A+?

Why so much bean counting?

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).

Why you force me to visit a separate website instead of using IVLE?

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'.

Why slides are not detailed?

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.

Why so much self-study?

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.

What if I don't carry around a laptop?

Why very narrow project scope?

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.

Why project requirements are so vague?

"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.

Why I'm not allowed to use my favorite tool/framework/language etc.?

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:

• Sometimes 'good enough', not necessarily the best, tools are a better fit for beginners: Most bleeding edge, most specialized, or most sophisticated tools are not suitable for a beginner course. After mastering our toolset, you will find it easy to upgrade to such high-end tools by yourself. We do expect you to eventually (after this module) migrate to better tools and, having learned more than one tool, to attain a more general understanding about a family of tools.
• We want you to learn to thrive under given conditions: As a professional Software Engineer, you must learn to be productive in any given tool environment, rather than insist on using your preferred tools. It is usually in small companies doing less important work that you get to chose your own toolset. Bigger companies working on mature products often impose some choices on developers, such as the project management tool, code repository, IDE, language etc. For example, Google used SVN as their revision control software until very recently, long after SVN fell out of popularity among developers. Sometimes this is due to cost reasons (tool licensing cost), and sometimes due to legacy reasons (because the tool is already entrenched in their code base).
  While programming in school is often a solo sport, programming in the industry is a team sport. As we are training you to become professional software engineers, it is important to get over the psychological hurdle of needing to satisfy individual preferences and get used to making the best of a given environment.

Practical reasons:

• Some of the LOs are tightly coupled to tools. Allowing more tools means tutors need to learn more tools, which increases their workload.
• We provide learning resources for tools. e.g. 'Git guides'. Allowing more tools means we need to produce more resources.
• When all students use the same tool, the collective expertise of the tool is more, increasing the opportunities for you to learn from each others.

Meanwhile, feel free to share with peers your experience of using other tools.

Why so many submissions?

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.

Why aren't we allowed to build a new product from scratch?

Why submission requirements differ between CS2103T and CS2101?

They do, and they should.

CS2103T 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.

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?)we the teaching team are 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?'

Note: 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?

What not to do:

When faced with a technical problem or a doubt about a concept, don'f fire off an email lecturer/tutor immediately after you encounter a problem or a doubt, unless it is something only the lecturer/tutor is supposed to know. Instead, here are some things you can do:

• Check what is given: Check if the problem/concept has been discussed in the lectures, text book, 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

• [lifehacker article]  Google Tips and Tricks Every Student Should Know
• [Article] How To Ask Questions The Smart Way by Eric Steven Raymond

Create a GitHub profile

Create a personal GitHub account if you don't have one yet.

1. You are advised to choose a sensible GitHub username as you are likely to use it for years to come in professional contexts.
2. Strongly recommended: Complete your GitHub profile. In particular,
   • Specify your full name.
   • Upload a suitable profile photo (i.e. a recent photo of your face).

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.

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. Some examples can be seen in the 'Teaching team' page. Given below are some examples of good and bad profile photos.

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 feed 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 :

• Re-allocate to others any mission-critical work allocated to that person so that such team members cannot bring down the entire team.
• However, do not leave out such team members from project communications. Always keep them in the loop so that they can contribute any time they wish to.
• Furthermore, evaluate them sincerely and fairly during peer evaluations so that they do get the grade their work deserves, no more, no less.
• Be courteous to such team members too. Some folks have genuine problems that prevent them from contributing more although they may not be able tell you the reasons. Just do your best for the project and assume everyone else is doing their best too, although their best may be lower than yours.