SG #4: SOFTWARE MAINTENANCE

Activity Title: Bug Hunt and Refactor Quest

Learning Outcomes:

Understand real-world software maintenance tasks.

Practice debugging, reading legacy code, and refactoring.

Learn the importance of clear documentation and code readability.

Objective:

Students will explore the concepts of software maintenance by identifying bugs, making
improvements, and refactoring code in an existing software project.

Instructions:

Part 1: Setup

Provide a sample codebase with:

At least 3 minor bugs or issues (logic errors, performance issues, outdated libraries,
etc.)

Poor naming conventions or documentation

A few opportunities for refactoring (e.g., duplicated code, long functions)

(Optional: You can use a simple open-source Python project or create your own
sandbox project.)

Part 2: Maintenance Tasks

Students will:

Identify Bugs

Run the program and list all bugs or unexpected behaviors they encounter.
Suggest fixes and justify their choices.

Improve the Code

Refactor functions or methods to improve readability and efficiency.

Apply better naming conventions.

Write or update documentation (docstrings/comments).

Add a Feature

Based on the existing project, propose and implement a small new feature.

Deliverables: (use coupon bond any size)

A handwritten short report covering:

Bugs found and fixed

Code before and after refactoring

Reasoning behind their changes

Updated version of the codebase (added feature)

Part 1: Setup - Identified Bugs and Issues

Here are the bugs and issues present in the initial codebase:
1. Logic Error in display_message: The if condition checks for the existence of a
variable named message, but the function receives the message as a parameter
named msg. If message is not defined elsewhere in the scope, this could lead to a
NameError. Even if message is defined globally, the function isn't using the
intended message passed to it.
2. Performance/Readability Issue with calculate: The calculate function performs two
distinct calculations (area and perimeter) and prints them. This lacks modularity
and makes the function less reusable. If we only need the area or the perimeter,
we still execute both. The docstring is also unhelpful.
3. Inconsistent and Poor Naming Conventions:
o Variables l and w are too short and don't clearly indicate their purpose
(length and width).
o Later in the code, we have length_rect and width_rect, which are better but
inconsistent with l and w.
o The function parameter names a and b in calculate are not descriptive.
o The parameter names le and wi in area_calc and perimeter_calc are also
inconsistent with the other naming conventions.
 4. Poor Documentation: The docstring for the calculate function ("This function does
some calculations.") provides no meaningful information about what the function
actually calculates or its parameters.
5. Duplicated Code: The logic for calculating the area and perimeter is present
within the calculate function and then repeated in the area_calc and perimeter_calc
functions. This violates the DRY (Don't Repeat Yourself) principle.
Part 2: Maintenance Tasks - Solutions
Here's a possible approach to addressing the identified issues:

1. Identify Bugs (Answers):

 Bug 1: Logic error in display_message. The if condition should check msg instead of
message.
o Suggested Fix: Change the if condition to if msg:. This ensures the function
uses the message passed to it as an argument.
o Justification: The intention is to check if a message was provided to the
function and print it if so. The parameter holding the message is msg, not
message.
2. Improve the Code (Refactoring, Naming, Documentation):
 Refactoring calculate:
o Before:
Python

def calculate(a, b):

'''This function does some calculations.'''
res1 = a * b
res2 = 2 * (a + b)
print("The result is: ", res1)
print("Another result is: ", res2)
o After:
def calculate_area(length, width):

"""Calculates the area of a rectangle.

Args:
length: The length of the rectangle.
width: The width of the rectangle.

Returns:
The area of the rectangle.
"""
return length * width

def calculate_perimeter(length, width):

"""Calculates the perimeter of a rectangle.

Args:
length: The length of the rectangle.
width: The width of the rectangle.
 Returns:
The perimeter of the rectangle.
"""
return 2 * (length + width)
```
* **Reasoning:** Separating the area and perimeter calculations into distinct functions improves
code organization, readability, and reusability. Each function now has a single responsibility.
 Applying Better Naming Conventions:
o Replace l with rectangle_length or length.
o Replace w with rectangle_width or width.
o Rename the parameters of calculate_area and calculate_perimeter to length
and width for consistency.
o Rename length_rect to rectangle2_length or length2 for clarity (or ideally,
choose one consistent naming style).
o Rename width_rect to rectangle2_width or width2.
o Rename le to length and wi to width in area_calc and perimeter_calc to match
the refactored functions.
 Writing/Updating Documentation:
o The docstrings for calculate_area and calculate_perimeter are now more
informative, explaining what each function does, its parameters, and what
it returns.
o We could add comments to explain more complex logic if needed (though
this simple example doesn't require much).
3. Add a Feature:
 Proposed Feature: Add a function to check if the rectangle is a square.
 Implementation:
Python

def is_square(length, width):

"""Checks if a rectangle is a square.

Args:
length: The length of the rectangle.
width: The width of the rectangle.

Returns:
True if the rectangle is a square, False otherwise.
"""
return length == width
Updated Version of the Codebase (with fixes, refactoring, and the new feature):
Python

# This program calculates the area and perimeter of a rectangle.

length = 5 # length of the rectangle

width = 10 # width of the rectangle

def calculate_area(length, width):

"""Calculates the area of a rectangle.
 Args:
length: The length of the rectangle.
width: The width of the rectangle.

Returns:
The area of the rectangle.
"""
return length * width

def calculate_perimeter(length, width):

"""Calculates the perimeter of a rectangle.

Args:
length: The length of the rectangle.
width: The width of the rectangle.

Returns:
The perimeter of the rectangle.
"""
return 2 * (length + width)

print("Area:", calculate_area(length, width))

print("Perimeter:", calculate_perimeter(length, width))

def display_message(msg):
"""Displays an important message.

Args:
msg: The message to be displayed.
"""
if msg:
print("Important Info:", msg)

message = "Calculations complete."

display_message(message) # Corrected: Using the globally defined 'message'

# Let's try with different values

length2 = 7
width2 = 3
print("Area 2:", calculate_area(length2, width2))
print("Perimeter 2:", calculate_perimeter(length2, width2))

def is_square(length, width):

"""Checks if a rectangle is a square.

Args:
length: The length of the rectangle.
width: The width of the rectangle.

Returns:
True if the rectangle is a square, False otherwise.
"""
return length == width
print("Is the first rectangle a square?", is_square(length, width))
print("Is the second rectangle a square?", is_square(length2, width2))
This provides a comprehensive set of answers and a well-maintained version of the
initial codebase. Students can use this as a reference to compare their findings and
solutions. Remember that there might be other valid approaches to refactoring and
naming, but this provides a clear and reasonable solution.