PS3: Introduction to refactoring - Qualité de Développement

Objectives¶

The goal of this session is to understand the following points:

Exercise 1 : Short functions¶

Code organization¶

Create a short-functions/ directory inside PS3/.
Create the following files inside short-functions/.

product.h

product.cpp

display-prices.h

display-prices.cpp

main.cpp

#ifndef PRODUCT_H
#define PRODUCT_H

#include <string>

class Product {
private:
    std::string mName;
    double mPrice; // in euros
    int mQuantity; // in units

public:
    Product(const std::string& name, double price, int quantity);
    std::string getName() const;
    double getPrice() const;
    int getQuantity() const;
    bool operator<(const Product& other) const;
};

#endif

#include "product.h"
#include <string>

Product::Product(const std::string& name, double price, int quantity) 
    : mName(name), mPrice(price), mQuantity(quantity) {}
    
std::string Product::getName() const { 
    return mName; 
}
        
double Product::getPrice() const { 
    return mPrice; 
}

int Product::getQuantity() const { 
    return mQuantity; 
}

bool Product::operator<(const Product& other) const {
    return mPrice < other.mPrice;
}

#include "product.h"
#include "display-prices.h"
#include <iostream>
#include <vector>
#include <algorithm>

void displayAvailableProductsByNonDecreasingPriceAndDisplayTotalPrice(){
	
    // Fetching products data
    std::vector<Product> products;
    // Our current products
    products.push_back(Product("Laptop", 1000, 5));
    products.push_back(Product("Smartphone", 700, 0));
    products.push_back(Product("Tablet", 500, 2));
    products.push_back(Product("Headphones", 150, 10));
    products.push_back(Product("Smartwatch", 200, 0));

    // Fetching available products data
	std::vector<Product> availableProducts;
    for (const Product& product : products) {
        if (product.getQuantity() > 0) {
            availableProducts.push_back(product);
        }
    }

    // Sorting available products by non-decreasing price
	sort(availableProducts.begin(), availableProducts.end());

    // Calculating total price
    double totalPrice = 0;
    for (const Product& product : availableProducts) {
        totalPrice += product.getPrice() * product.getQuantity();
    }

    // Displaying available products by non-decreasing price
	std::cout << "Sorted Available Products (by non-decreasing price):" << std::endl;
    for (const Product& product : availableProducts) {
        std::cout << "Name: " << product.getName() << " - Price: " << product.getPrice() 
             << " - Quantity: " << product.getQuantity() << std::endl;
    }

    // Displaying total price
    std::cout << "Total Price of Available Products: " << totalPrice << std::endl;
}

Include guards

These directives together form an include guard :

#ifndef PRODUCT_H
#define PRODUCT_H

//...

#endif

#define creates a macro that replaces the defined text (PRODUCT_H) with the following code. The naming convention for macros is the same as for global constants and includes _H to indicate that it is a macro related to the include guard of a header (though other types of macros may exist).
#ifndef (short for “if not defined”), #define, and #endif mean: “If the macro PRODUCT_H is not defined, define the macro PRODUCT_H as follows: <code>, end of the condition”.

The include guard ensures that a header is included only once in each source code and therefore in each translation unit.

The downside of include guards is the need for a consistent naming scheme for an executable (whose compilation can come from thousands of different files spread across different directories): there cannot be two headers with the same macro (even if the files are in very distant directories from each other).

Another directive is sometimes used instead of include guards, but it also has its own drawbacks.
Standard best practices in C++ recommend using include guards.

Compile the code with g++ -o short-functions main.cpp display-prices.cpp product.cpp (the order of .cpp files does not matter).

C++ version

If you see warnings during compilation related to the syntax standards used (for example, for (ElementType element : vectorOfElements), which only exists since C++11), you can compile with a more recent version of C++ that is compatible with your g++ compiler.

To check the version (year) of C++ used by default by g++ on your workstation, use the following command:

g++ -dM -E -x c++ /dev/null | grep __cplusplus | sed 's/[^0-9]*\([0-9]\{4\}\)[0-9]*L/\1/'

For example, 2011 corresponds to C++11.

To check the versions compatible with g++ on your workstation, use the command:

g++ -v --help 2> /dev/null | grep -oP '(?<=-std=)c\+\+\S+' | sed 's/\.$//' | sort | uniq

The latest C++ versions after 11 are C++14, 17, 20, and 23.

You can compile your code using a more recent and compatible version than the default one. For example:

g++ -std=c++14 -o short-functions main.cpp display-prices.cpp product.cpp

Run ./short-functions.

Summary of good code organization practices in C++

Do not put everything in a single file.
Use a .cpp file and a corresponding .h file for each class and each group of related external functions, and then a main.cpp file.
A .cpp and .h file for a class should carry the name of the class, and a .cpp and .h file for external functions should carry the name that links them.
.h files should contain only declarations, and .cpp files should contain definitions.
.h files must always have include guards, i.e.:

#ifndef HEADER_NAME_H
#define HEADER_NAME_H

//...

#endif

Do not forget to use MyClass:: in front of methods in my-class.cpp that define the class MyClass declared in my-class.h.
If you need the elements defined in a code.cpp file, then #include "code.h" (which declared those elements), not code.cpp itself.
Include what you see: Add the libraries and headers you use for your code at the beginning, even if a header you include already contains them.
No longer use using namespace std.

Java and C#

In Java and C#, there is no separation between headers and source code files, as their compilation systems are different. Code elements are both declared and defined in the same file.
However, it remains essential to organize the code into multiple files, just like in C++.
In Java and C#, it is necessary to name a file containing a class after the class itself (like in C++), but using the UpperCamelCase convention (also called PascalCase). Additionally, in Java, compilation will fail if the file containing a class is not correctly named, unlike in C++.
In Java and C#, the principle of Include what you use is followed, meaning that only what is necessary for the code to function properly is imported (import in Java, using in C#). This differs from the Include what you see principle in C++, which relies on include guards to prevent code duplication.

Refactoring the code¶

What does this code do?

Quiz: What are the issues with the code of displayAvailableProductsByNonDecreasingPriceAndDisplayTotalPrice?
Refactor the code of display-prices.cpp (by modifying the other affected files, such as the header and main).

Exercise 2: Classify it¶

Create a directory classify-it/ (within which the code will be organized into several different files).
In classify-it/, create the following file.

main.cpp

#include <iostream>
#include <string>
#include <vector>

double calculateAverage(const std::vector<double>& scores) {
    double sum = 0;
    for (double score : scores) {
        sum += score;
    }
    return sum / scores.size();
}

void printScores(const std::string& studentName, int studentId, const std::vector<double>& scores) {
    std::cout << std::endl << "Scores for " << studentName << " (Id: " << studentId << "): ";
    for (size_t i = 0; i < scores.size(); i++) {
        std::cout << "[" << i+1 << "] " << scores[i] << " ";
    }
    std::cout << std::endl;
}

void printAverage(const std::vector<double>& scores){
    std::cout << "Average: " << calculateAverage(scores) << std::endl;
}

int main() {
    std::string studentName;
    int studentId;
    std::vector<double> scores;

    studentId = 12345;
    studentName = "Alice";

    scores.push_back(11);
    scores.push_back(12.5);
    scores.push_back(14.75);
    scores.push_back(19);

    printScores(studentName, studentId, scores);

    return 0;
}

What does this code do?

It is difficult to add students and their grades.
We are therefore going to create a Student class with the following three attributes:

Only the student’s Id is necessary to construct the object. The Id is immutable: once initialized by the constructor, it cannot be modified. This is made possible by using const in front of the attribute.

Initializing a const attribute

An immutable (const) attribute can only be initialized in the initializer list in C++.
For example:

class MyClass{
private:
    const int mAttribute;
public:
    MyClass(int valueName) : mAttribute(valueName){
        // Constructor body
    }
}

This attribute cannot be initialized in the constructor body. For example, the following code will result in a compilation error:

class MyClass{
private:
    const int mAttribute;
public:
    MyClass(int valueName) {
        mAttribute = valueName;
    }
}

The student’s name can be modified. Initially, it is empty (by default, an uninitialized string someString is == ""). We will not handle potential errors from an empty name in this exercise.

The student’s vector of scores will not be accessible. The only access will be through displaying (printScores) and adding scores via the appendScore function, which adds a score to the end of the vector using push_back. There are no scores initially, but we will also ignore potential errors coming from an empty vector in this exercise.

Create the Student class with the appropriate methods (including the corresponding .h and .cpp files), and add functions to calculate the average and display the scores.
Modify the main.cpp directives to include student.h and the necessary libraries.

User input (Bonus)¶

The benefit of having a Student class is to make it easier to enter data for multiple students.
In order to input data for several students, we will write several functions to handle user input.

Create a file user-input.cpp along with the associated header file.
Here are some function declarations to help you:

void inputNumberOfStudents(int& number);
void inputStudentId(int& id);
void inputStudentName(Student& student);
void inputStudentScores(Student& student);
Student createStudentFromInput();
void printAllScoresAndAverages(const std::vector<Student>& students);

Here is the code of inputStudentScores to help you:

void inputStudentScores(Student& student) {
    double score;
    std::cout << "Enter score (-1 to stop): ";
    std::cin >> score;

    while (score != -1) {
        student.appendScore(score);
        std::cout << "Enter score (-1 to stop): ";
        std::cin >> score;
    }
}

Implement the given functions and modify main to retrieve user input and display the grades as well as the averages for each student.

Return to the objectives and check the points you have mastered. Review the points you have not yet fully understood. Ask your instructor for help if needed.

Practical Sessions

PS2: How to rename things?

Practical Sessions

PS4: Build system and documentation