CSC/ECE 517 Fall 2024 - E2452. Refactor review mapping controller.rb

Expertiza Background

The open-source project Expertiza is built using Ruby on Rails, maintained by both the staff and students at NC State. This platform grants instructors complete authority over managing class assignments. Expertiza is packed with versatile tools to support various types of assignments, including options for peer evaluations, forming groups, and adding topics. For a comprehensive overview of all that Expertiza provides, visit the Expertiza wiki.

About Controller

The `review_mapping_controller` function is responsible for assigning reviewers to specific assignments. This controller plays a key role in allocating reviews across different student groups or individuals, handling both peer and self-assessment scenarios. Additionally, it manages student requests for reviews and facilitates extra bonus reviews that align with the assignment's requirements.

Functionality of review_mapping_controller

The `review_mapping_controller` is a vital part of a system dedicated to managing the assignment and allocation of reviewers for different types of evaluations, such as peer reviews and self-assessments. Its main role is to coordinate the assignment of these reviews across individual students or various groups, using an intricate process that factors in elements like fairness, diverse perspectives, and alignment with assignment criteria. Through this coordination, the controller ensures that every participant receives a thorough and balanced assessment, supporting the overall quality and reliability of the evaluation process.

In addition, the `review_mapping_controller` is essential for handling student requests for additional assessments, often driven by needs for extra feedback, additional credit opportunities, or reevaluation. When processing these requests, the controller must adhere to assignment guidelines and carefully evaluate the feasibility of granting extra assessments without affecting the integrity or fairness of the review process. This may involve accounting for practical constraints, such as reviewer availability and workload distribution, to ensure an equitable experience for all participants.

Problem Statement

The `review_mapping_controller` poses challenges due to its extensive size, complexity, and lack of comments, which make it hard for developers to fully understand its functions. To improve this, a thorough refactoring is recommended to divide lengthy methods into smaller, more understandable sections. This approach would break down complex logic into modular parts, each handling a particular task within the controller’s scope. Additionally, refactoring should focus on eliminating redundant code, consolidating repeated segments into reusable functions or utilities to improve code quality and minimize errors. By reorganizing the controller code and enhancing its documentation, developers can gain a clearer insight into its functionality, simplifying maintenance, troubleshooting, and potential updates.

Tasks

1. Refine Extensive Methods: Methods like `assign_reviewer_dynamically`, `add_reviewer`, `automatic_review_mapping`, and `peer_review_strategy` will be further broken down for greater clarity and efficiency.

2. Clarify Variable Names: Variables will be renamed to make their roles more transparent, enhancing readability and comprehension.

3. Use Subclass Methods Instead of Switch Statements: Existing switch statements will be replaced with subclass methods, contributing to a more modular and scalable code structure.

4. Introduce Subclass Models: New models for subclasses will be implemented to streamline organization and simplify management.

5. Eliminate Hardcoded Parameters: Any hardcoded parameters will be removed to increase adaptability across different use cases.

6. Enhance Comments: Additional comments will be included where helpful, and any vague or redundant comments will be clarified or removed.

7. Expand Test Coverage: The test suite will be extended to ensure thorough testing, particularly following the refactoring process.

Phase 1

1. Restructure the `assign_reviewer_dynamically` function to enhance its clarity and modular design.
2. Revise and improve the tests related to the `assign_reviewer_dynamically` function.
3. Simplify the `add_reviewer` function by breaking down its complex logic into smaller, more manageable components.
4. Update and broaden the tests associated with the `add_reviewer` function to ensure proper functionality.
5. Refine existing comments and introduce new ones to clarify intricate parts of the code.
6. Change variable names to make their purposes clear, allowing for immediate understanding.
7. Tackle and fix Code Climate issues to produce cleaner and more efficient code.
8. Obtained assignment details using the assignment ID, ensuring that an error message is displayed if a user is invalid (not found in the database), and that reviewer assignments are only made if the reviewer is confirmed as part of the assignment.
9. Collected participant details when a user was added to an assignment.

Test Cases

1. Verify that `assign_reviewer_dynamically()` correctly assigns a reviewer based on defined criteria.
2. Check that `add_reviewer()` successfully adds a reviewer to the system.
3. Ensure `automatic_review_mapping()` maps submissions to reviewers automatically.
4. Validate the logic of `peer_review_strategy()` for peer reviewer assignments.
5. Ensure all variables have been renamed according to the new naming conventions.
6. Confirm that all switch statements have been replaced with subclass methods.
7. Verify that hardcoded parameters have been removed and replaced with configurable options.
8. Check for meaningful comments and the removal of redundant or unclear comments.
9. Assess whether the test suite covers all critical functions and edge cases.
10. Test dynamic reviewer assignment for edge cases, such as no available reviewers.

Implementation

Restructuring assign_reviewer_dynamically

Original Code

The assign_reviewer_dynamically function contained multiple responsibilities, making it lengthy and challenging to follow.

Updated Code

The function was refactored to focus on specific tasks, such as:

• Validating user eligibility
• Fetching assignment details
• Assigning a reviewer only if they are confirmed as part of the assignment

Revising Tests for assign_reviewer_dynamically

Original Code

• The tests related to the assign_reviewer_dynamically function were limited and did not cover all scenarios.

Updated Code

• The tests have been improved and broadened to cover:
• Valid user scenarios
• Invalid user scenarios (e.g., user not found in the database)

Simplifying add_reviewer

Original Code

• The add_reviewer function had complex logic that hindered readability and maintainability.

Updated Code

• This function was simplified by breaking it down into smaller, manageable components that handle Parameter Validation, Sending notifications

Updating Tests for add_reviewer

Original Code

• The existing tests for add_reviewer were insufficient to ensure the function worked correctly in all situations.

Updated Code

Tests were expanded to include:

• Successful addition of reviewers
• Handling of invalid inputs

Refining Comments and Documentation

Original Code

• Comments in the original code were sparse and often unclear.

Updated Code

Descriptive comments were added throughout the code to explain:

• The purpose of each method
• The logic behind complex code sections

Changing Variable Names

Original Code

• Variable names were generic and did not convey their purposes.

Updated Code

• Variable names have been updated to be more descriptive, making their purposes immediately clear.

Implemented Screenshots

Test Case and code coverage          
                                                                 

Refactored assign_reviewer_dynamically to reduce nesting, improve readability, and streamline error handling with guard clauses and modularized logic.

Refactored `add_reviewer` to reduce complexity by extracting reviewer assignment logic into `assign_reviewer_to_contributor`, simplifying the method and improving readability through guard clauses for error handling.

Refactored `automatic_review_mapping` by extracting complex logic for standard, calibrated, and uncalibrated artifact mapping into helper methods (`handle_standard_review_mapping` and `handle_calibrated_and_uncalibrated_artifacts`), reducing method length and improving readability. Guard clauses were introduced for early exit conditions, and variable assignments were streamlined to ensure single responsibility and modularity, making the method more maintainable and readable.

Team

Mentor

• Nainisha Bhallamudi

Members

• Gauri Verma
• Vaibhav Hawaldar
• Raj Kalantri

References

1. Expertiza
2. OSS Projects on Expertiza
3. Github
4. Pull Request
5. VCL Server