Week 5 [Mon, Sep 7th] - Topics

A software requirement specifies a need to be fulfilled by the software product.

A software project may be one of two types:

• a brownfield project, i.e., a project to replace or update an existing software product
  Example Adding an online payment option to a university's existing course registration system.
• a greenfield project, i.e., a project to develop a new system from scratch
  Example Building a new app that lets students swap tutorial slots, where no such system exists yet.

In either case, requirements need to be gathered, analyzed, specified, and managed.

Requirements come from stakeholders.

Identifying requirements is often not easy.
Example Stakeholders may not be aware of their precise needs, may not know how to communicate their requirements correctly, or may not be willing to spend effort identifying requirements.

Requirements can be divided into two in the following way:

1. Functional requirements specify what the system should do.
   Example The system should allow a user to search for a book by its title.
2. Non-functional requirements specify the constraints under which the system is developed and operated.
   Example The search should return results within two seconds.

You may have to spend extra effort identifying NFRs as early as possible because:

1. NFRs are easier to miss.
   Example Stakeholders tend to think of functional requirements first.
2. Sometimes NFRs are critical to the success of the software.
   Example A web application that is too slow or that has weak security is unlikely to succeed even if it has all the right functionality.

Requirements can be prioritized based on the importance and urgency, while keeping in mind the constraints of schedule, budget, staff resources, quality goals, and other constraints.

A common approach is to group requirements into priority categories. Note that all such scales are subjective, and stakeholders define the meaning of each level in the scale for the project at hand.

Some requirements can be discarded if they are considered ‘out of ’.

Here are some characteristics of well-defined requirements ^{[📖 zielczynski]}:

• Unambiguous
• Testable (verifiable)
• Clear (concise, terse, simple, precise)
• Correct
• Understandable
• Feasible (realistic, possible)
• Independent
• Necessary
• Implementation-free (i.e., abstract)

Two of these carry most of the weight: a requirement that is unambiguous and testable states an observable result, so evidence can settle whether it has been met. A requirement that states a judgment instead can only be settled by argument. To make one testable, say who is involved, what they are doing, and what result counts as success.

Besides these criteria for individual requirements, the set of requirements as a whole should be:

• Consistent
• Non-redundant
• Complete

Requirements are not settled once and then left alone; they keep changing while the product is being built. Three reasons account for most of it:

1. Stakeholders work out what they want by seeing something concrete.
   Example A user who could not describe the report they needed can say exactly what is wrong with the first version of it.
2. The world the product lives in changes.
   Example A new regulation comes into force, or a competitor ships a feature that users now expect.
3. The team learns what things actually cost.
   Example A requirement turns out to take ten times the effort everyone assumed, which changes whether it is worth having at all.

Two things follow from this.

A specification that is not kept up to date does not become harmless, it becomes misleading, because people keep acting on it. A developer builds the version that was superseded a month ago; a tester reports a defect against behavior nobody wants any more.

Every change is also a decision about what will not be built. Accepting a new requirement late competes with requirements already agreed, so priorities have to be revisited rather than settled once at the start.

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.

Studying existing products can unearth shortcomings that a new product can address. Product manuals and other forms of documentation can tell us how existing solutions work.
Example 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.

Observing users in their natural work environment can uncover product requirements. Usage data from an existing system can also show how that system is being used, which can help in building a better replacement.
Example Usage data can reveal the situations where the user makes mistakes when using the current system.

Surveys can be used to solicit responses and opinions from a large number of stakeholders regarding a current product or a new product.

Interviewing stakeholders and domain experts can produce useful information about project requirements. How much it produces depends far more on how the interview is run than on how long it lasts.

1. Find out what the person is responsible for before you meet them, and decide what only they can tell you. An interview spent on things you could have looked up is a wasted one.
2. Open with something concrete rather than an abstract question. 'What do you need?' invites a vague answer, or a feature request that hides the need behind it. Walking through a recent situation, a screen of the current system, or a prototype gets you specifics.
3. Ask what goes wrong today and what they do instead. Workarounds are where unmet requirements hide: if someone keeps a private spreadsheet, the system is failing them in a way worth understanding.
4. Play the answer back in your own words before moving on. It is very common for both sides to leave an interview believing they agreed, having understood different things.
5. Confirm your written notes with the interviewee afterwards. They can correct what you misheard while they still remember what they said.

Treat what you hear as claims to be checked, rather than requirements to be recorded. People often describe the process they are supposed to follow rather than the one they actually follow, and two stakeholders can want things that cannot both be true.
Example One department wants every leave application approved by a manager; another wants short absences to need no approval at all.

Focus groups are a kind of informal interview within an interactive group setting. A group of people (e.g. potential users, beta testers) is asked about their understanding of a specific issue, process, product, advertisement, etc.

Prototyping can uncover requirements, in particular, those related to how users interact with the system. UI prototypes or mock-ups, also called wireframe diagrams, are often used in brainstorming sessions or in meetings with users to get quick feedback.

Prototyping can be used for discovering as well as specifying requirements e.g. a UI prototype can serve as a specification of what to build.

Gathering requirements tells you what people said; validating requirements tells you whether what you wrote down is what they meant. It is worth distinguishing from the check that comes much later:

• Validating requirements asks whether you have written down the right thing.
• Verifying software asks whether what was built matches what was written down.

A team that only does the second can build exactly the wrong product, correctly.

Three checks are cheap enough to run on a student project:

1. Walk the requirement back to the stakeholder in words they would use, and wait for the correction. Reading your own notes aloud to the person who gave them to you finds misunderstandings faster than any amount of rereading them yourself.
2. Put something in front of a user instead of describing it. People correct a rough sketch or a mock-up far more readily than they correct a paragraph, because they can see what they would actually be given.
3. State the observable result that would settle the requirement. If nobody can say what would count as having met it, the requirement is not yet saying anything a team could build against.

A requirement you cannot yet state in observable terms is not wrong, it is not ready. Record it as an open question, or as the next thing to put a prototype in front of. A product vision, an unresolved disagreement between two stakeholders, or a quality concern that nobody has quantified yet are all legitimate inputs at this stage; deleting them because they cannot be phrased as a check yet would throw away the very things most worth resolving.

A textual description (i.e., prose) can be used to describe requirements. Prose is especially useful when describing abstract ideas such as the vision of a product.

Avoid using lengthy prose to describe requirements; they can be hard to follow.

A common format for writing user stories is:

You can write user stories using a physical medium or a digital tool. For example, you can use index cards or sticky notes, and arrange them on walls or tables. Alternatively, you can use software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.

User stories in use

With sticky notes

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

---

With paper

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

---

With software

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

---

---

The {benefit} can be omitted if it is obvious.

It is recommended to confirm there is a concrete benefit even if you omit it from the user story. If not, you could end up adding features that have no real benefit.

You can add more characteristics to the {user role} to provide more context to the user story.

You can write user stories at various levels. High-level user stories, called epics (or themes) cover bigger functionality. You can then break down these epics into multiple user stories of normal size.

You can add conditions of satisfaction to a user story to specify things that need to be true for the user story implementation to be accepted as ‘done’.

These are more widely known as acceptance criteria. Whatever they are called, they are the part of a story that states an observable result, and therefore the part that survives when the conversation behind the story does not.

Other useful information that can be added to a user story includes (but is not limited to):

• Priority: how important the user story is
• Size: the estimated effort to implement the user story
• Urgency: how soon the feature is needed

User stories capture user requirements in a way that is convenient for , , and .

[User stories] strongly shift the focus from writing about features to discussing them. In fact, these discussions are more important than whatever text is written. _{[Mike Cohn, MountainGoat Software 🔗]}

User stories differ from mainly in the level of detail. User stories should only provide enough details to make a reasonably low-risk estimate of how long the user story will take to implement. When the time comes to implement the user story, the developers will meet with the customer face-to-face to work out a more detailed description of the requirements. [more...]

Leaving out detail on purpose relies on the implementer being able to come back and ask. Where asking is slow or does not happen at all — work handed to another team across a time zone, or generated in a single pass by an AI coding assistant with no round of clarification — an unstated detail never surfaces as a question. It gets filled in with a plausible guess, and the guess arrives faster than the question ever would.
Example 'As a user, I can delete a task' leaves open whether deleting is recoverable. Someone who can ask, asks. Someone working from the story alone picks one, and the answer looks finished either way.

The further the implementer sits from the conversation, the more of a story's meaning has to survive in writing — which is the job the acceptance criteria are doing.

User stories can capture non-functional requirements too because even NFRs must benefit some stakeholder.

While user stories can be recorded on in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not .

Specifying a term in the glossary is useful in the following cases:

• A domain-specific/technical term that may not be known to all stakeholders, to indicate its definition
• When a term has multiple meanings, to indicate which of them is used in the project
• When there are multiple terms used for the same concept, to indicate which of them will be used in the project

A supplementary requirements section can be used to capture requirements that do not fit elsewhere. Typically, this is where most Non-Functional Requirements will be listed.

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 readability (aka 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 you do not intend to pass the code to someone else, code quality is still important because you will become a 'stranger' to your own code someday.

Avoid long methods as they often contain more information than what the reader can process at a time. Consider if shortening is possible when a method goes beyond 30 . 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 Coding Style}

Avoid deep nesting -- the deeper the nesting, the harder it is for the reader to keep track of the logic.

In particular, avoid arrowhead style code.

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def calculate_subs():
    if not age:
        if not sub:
            if not not_fulltime:
                subsidy = 500
            else:
                subsidy = 250
        else:
            subsidy = 250
    else:
        subsidy = -1
    return subsidy

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def calculate_subsidy():
    if is_senior:
        return REJECT_SENIOR
    elif is_already_subsidized:
        return SUBSIDIZED_SUBSIDY
    elif is_parttime:
        return FULLTIME_SUBSIDY * RATIO
    else:
        return FULLTIME_SUBSIDY

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Avoid complicated expressions, especially those having many negations and nested parentheses. If you must evaluate complicated expressions, have them done in steps (i.e., calculate some intermediate values first and use them to calculate the final value).

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

boolean isUrgent = typeCode == URGENT;

return isValidCode && isUrgent;

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

return ((length < MAX_LENGTH) or (previous_size != length)) and (type_code == URGENT)

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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}

Avoid magic numbers in your code. When the code has a number that does not explain the meaning of the number, it is called a "magic number" (as in "the number appears as if by magic"). Using a makes the code easier to understand because the name tells us more about the meaning of the number.

return 3.14236;
...
return 9;

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

static final double PI = 3.14236;
static final int MAX_SIZE = 10;
...
return PI;
...
return MAX_SIZE - 1;

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

return 3.14236
...
return 9

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

PI = 3.14236
MAX_SIZE = 10
...
return PI
...
return MAX_SIZE - 1

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Similarly, you can have ‘magic’ values of other data types.

return "Error 1432"; // A magic string!

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

return "Error 1432" # A magic string!

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Avoid any magic literals in general, not just magic numbers.

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

• [Java] Use explicit type conversion instead of implicit type conversion.
• [Java, Python] Use parentheses/braces to show groupings even when they can be skipped.
• [Java, Python] 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'.

Lay out the code so that it adheres to the logical structure. The code should read like a story. Just as you 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 separate groups of related statements.

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.

statement A1
statement A2
statement A3
statement B1
statement C1
statement B2
statement C2

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

statement A1
statement A2
statement A3

statement B1
statement B2

statement C1
statement C2

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

• unused parameters in the method signature
• similar things that look different
• different things that look similar
• multiple statements in the same line
• data flow anomalies, such as assigning values to variables and then modifying them before using the assigned values

Do not try to write ‘clever’ code. “Keep it simple, stupid” (KISS), as the old adage goes. 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:

• You 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 readability.
• Hand-optimized code can be harder for the compiler to optimize (the simpler the code, the easier it is for the compiler to optimize). 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.

Make it work, make it right, make it fast is a popular saying in the industry, 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 no matter how fast/efficient it is.

Premature optimization is the root of all evil in programming. _{-- Donald Knuth}

Of course, there are cases in which optimizing takes priority over other things e.g., when writing code for resource-constrained environments. This guideline is simply a caution that you should optimize only when needed.

Avoid having multiple levels of abstraction within a code fragment. Note: The book The Productive Programmer (by Neal Ford) calls this the Single Level of Abstraction Principle (SLAP) while the book Clean Code (by Robert C. Martin) calls this One Level of Abstraction per Function.

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Also ensure that the code is written at the highest level of abstraction possible.

low-level statement A1
low-level statement A2
low-level statement A3
low-level statement B1
low-level statement B2
if condition X :
    low-level statement C1
    low-level statement C2

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

high-level step A
high-level step B
if condition X:
  high-level step C

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

That said, it is sometimes possible to pack two levels of abstraction into the code without affecting readability that much, provided each step in the higher-level logic is clearly marked using comments and separated (e.g., using a blank line) from adjacent steps.

//high-level step A
low-level statement A1
low-level statement A2
low-level statement A3

//high-level step B
low-level statement B1
low-level statement B2

if condition X :
    //high-level step C
    low-level statement C1
    low-level statement C2

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The happy path should be clear and prominent in your code. Restructure the code to make the happy path (i.e., the execution path taken when everything goes well) less-nested as much as possible. It is the ‘unusual’ cases that should be nested. 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.

if (!isUnusualCase) {  //detecting an unusual condition
    if (!isErrorCase) {
        start();    //main path
        process();
        cleanup();
        exit();
    } else {
        handleError();
    }
} else {
    handleUnusualCase(); //handling that unusual condition
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

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

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

for (condition1)
    if (condition2)
        statement A
        statement B
        statement C
        statement D
statement E

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

for (condition1)
    if (not condition2)
        continue
    statement A
    statement B
    statement C
    statement D
statement E

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

It is safer to use language constructs in the way they are meant to be used, even if the language allows shortcuts. Such coding practices are common sources of bugs. Know them and avoid them.

Always include a default branch in case statements. This ensures that all possible outcomes have been considered at the branching point.

Furthermore, use the default branch 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, raise a suitable error). 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";

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

• Use one variable for one purpose. Do not reuse a variable for a 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;  // parameter reused as a variable
    return length;
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def compute_rectangle_area(length, width):
    length = length * width
    return length

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def compute_rectangle_area(length, width):
    area = length * width
    return area
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Avoid empty catch statements, as they are a way to ignore errors silently (which is not a good thing). In cases when it is unavoidable, at least give a comment to explain why the catch block is left empty.

Get rid of unused code the moment it becomes redundant. You might feel reluctant to delete code you have painstakingly written, even if you have no use for that code anymore ("I spent a lot of time writing that code; what if I need it again?"). Consider all code as baggage you have to carry. 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.

Minimize global variables. Global variables may be the most convenient way to pass information around, but they 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}

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.

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 Code Complete}

Some think commenting heavily increases the 'code quality'. That is not so. Avoid writing comments to explain bad code. Improve the code to make it self-explanatory.

Do not repeat in comments information that is already obvious from the code. If the code is self-explanatory, a comment may not be needed.

//increment x
x++;

//trim the input
trimInput();

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

# increment x
x = x + 1

# trim the input
trim_input()

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Write comments targeting other programmers reading the code. Do not write comments as if they are private notes to yourself. One type of comment that is almost always useful is the header comment that you write for a class or an operation to explain its purpose.

// a quick trim function used to fix bug I detected overnight
void trimInput() {
    ....
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def trim_input():
"""a quick trim function used to fix bug I detected overnight"""
    ...

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def trim_input():
"""Trim the input of leading and trailing spaces"""
    ...

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Comments should explain the WHAT and WHY aspects of the code, rather than the HOW aspect.

WHAT: The specification of what the code is supposed to do. The reader can compare such comments to the implementation to verify if the implementation is correct.

/** Removes all spaces from the {@code input} */
void compact(String input) {
    input.trim();
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

WHY: The rationale for the current implementation.

// Remove spaces to comply with IE23.5 formatting rules
compact(input);

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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.

// return true if both left end and right end are correct
//    or the size has not incremented
return (left && right) || (input.size() == size);

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The process of restructuring code in small steps without modifying its external behavior is called refactoring. Refactoring is needed because the first version of the code you write may not be of production quality. It is OK to first concentrate on making the code work, rather than worry over the quality of the code, as long as you improve the quality later.

• Refactoring is not rewriting: Discarding poorly written code entirely and rewriting it from scratch is not refactoring because refactoring needs to be done in small steps.
• Refactoring is not bug fixing: By definition, refactoring is different from bug fixing or any other modification that alters the external behavior (e.g., adding a feature) of the component concerned.

Refactoring code can have many secondary benefits, e.g.,

• hidden bugs become easier to spot
• performance can improve (sometimes, simpler code runs faster than complex code because it is easier for the compiler to optimize).

Given below are two common refactorings (more).

if (isSpecialDeal()) {
    total = price * 0.95;
    send();
} else {
    total = price * 0.98;
    send();
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

if (isSpecialDeal()) {
    total = price * 0.95;
} else {
    total = price * 0.98;
}
send();


    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

if is_special_deal:
    total = price * 0.95
    send()
else:
    total = price * 0.98
    send()

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

if is_special_deal:
    total = price * 0.95
else:
    total = price * 0.98

send()

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

void printOwing() {
    printBanner();

    // print details
    System.out.println("name:    " + name);
    System.out.println("amount    " + getOutstanding());
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

void printOwing() {
    printBanner();
    printDetails(getOutstanding());
}

void printDetails(double outstanding) {
    System.out.println("name:    " + name);
    System.out.println("amount    " + outstanding);
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def print_owing():
    print_banner()

    # print details
    print("name:    " + name)
    print("amount    " + get_outstanding())

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def print_owing():
    print_banner()
    print_details(get_outstanding())

def print_details(amount):
    print("name:    " + name)
    print("amount    " + amount)

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Some IDEs have built-in support for basic refactorings, such as automatically renaming a variable/method/class in all places it has been used.

Refactoring, even if done with the aid of an IDE, may still result in regressions. Therefore, each small refactoring should be followed by regression testing.

Refer to these se-edu guides:

• IntelliJ IDEA: Refactoring

There are refactoring catalogs listing various refactorings. Given below are some commonly used refactorings.

1. Consolidate Conditional Expression
2. Decompose Conditional
3. Inline Method
4. Remove Double Negative
5. Replace Magic Literal
6. Replace Nested Conditional with Guard Clauses
7. Replace Parameter with Explicit Methods
8. Reverse Conditional
9. Split Loop
10. Split Temporary Variable

One way to identify refactoring opportunities is by code smells.

A code smell is a surface indication that usually corresponds to a deeper problem in the system. First, a smell is by definition something that's quick to spot. Second, smells don't always indicate a problem.
--adapted from https://martinfowler.com/bliki/CodeSmell.html

An example (from the same source as above) is the code smell data class, i.e., a class with all data and no behavior. When you encounter such a class, you can explore whether moving the corresponding behavior into that class is appropriate. Some more examples:

• Long Method
• Large Class
• Primitive Obsession
• Temporary Field
• Shotgun Surgery

Periodic refactoring is a good way to pay off the technical debt a codebase has accumulated.

Software systems are prone to the build up of cruft - deficiencies in internal quality that make it harder than it would ideally be to modify and extend the system further. Technical Debt is a metaphor, coined by Ward Cunningham, that frames how to think about dealing with this cruft, thinking of it like a financial debt. The extra effort that it takes to add new features is the interest paid on the debt.
--https://martinfowler.com/bliki/TechnicalDebt.html

While it is important to refactor frequently to avoid accumulating 'messy' code (aka technical debt), an important question is how much refactoring is too much refactoring. It is too much refactoring when the benefits no longer justify the cost. The costs and the benefits depend on the context. That is why some refactorings are 'opposites' of each other (e.g., extract method vs inline method).

Assertions are used to define assumptions about the program state so that the runtime can verify them. An assertion failure indicates a possible bug in the code because the code has resulted in a program state that violates an assumption about how the code should behave.
Example An assertion can be used to express something like: when execution reaches this point, the variable v cannot be null.

If the runtime detects an assertion failure, it typically takes some drastic action such as terminating the execution with an error message. This is because an assertion failure indicates a possible bug and the sooner the execution stops, the safer it is.

int timeout = Config.getTimeout();
// set assertion here ...

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Use the assert keyword to define assertions.

x = getX();
assert x == 0 : "x should be 0";
...

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Assertions can be disabled without modifying the code.
Example java -enableassertions HelloWorld (or java -ea HelloWorld) will run HelloWorld with assertions enabled while java -disableassertions HelloWorld will run it without verifying assertions.

Enable assertions in IntelliJ (how?) and get an assertion to fail temporarily (e.g. insert an assert false into the code temporarily) to confirm assertions are being verified.

Java assert vs JUnit assertions: Both check for a given condition but JUnit assertions are more powerful and customized for testing. In addition, JUnit assertions are not disabled by default. Use JUnit assertions in test code and Java assert in functional code.

It is recommended that assertions be used liberally in the code. Their impact on performance is low and worth the additional safety they provide.

Do not use assertions to do work because assertions can be disabled. If assertions are disabled, your program will stop working when assertions are not enabled.

...
assert writeFile() : "File writing is supposed to return true";

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Assertions are suitable for verifying assumptions about Internal Invariants, Control-Flow Invariants, Preconditions, Postconditions, and Class Invariants. Refer to Programming with Assertions (second half) to learn more.

Exceptions and assertions are two complementary ways of handling errors in software but they serve different purposes. Therefore, both assertions and exceptions should be used in code.

• The raising of an exception indicates an unusual condition created by the user (e.g., the user inputs an unacceptable input) or the environment (e.g., a file needed for the program is missing).
• An assertion failure indicates the programmer made a mistake in the code (e.g., a null value is returned from a method that is not supposed to return null under any circumstances).

Java 8 introduced a number of new features (e.g., Lambdas, Streams) that are not trivial to learn but also extremely useful to know.

Here is an overview of new Java 8 features (written by Benjamin Winterberg).

See Git-Mastery → Lesson T9L3. Merging Pull Requests