Expertiza_Wiki - User contributions [en]

E1929 Visualizations for Instructors

2019-05-01T00:31:23Z

Gshugh: /* Code Changes */

== Introduction ==
This [http://wiki.expertiza.ncsu.edu/index.php/Expertiza_documentation Expertiza] project, completed in the Spring of 2019, aimed to improve the charts instructors could view to see the grade statistics for a given assignment. Two charts already existed, one showing the grade distribution for all teams, and another simply showing the class average grade. Our goal for this project was to add a third chart, using [https://developers.google.com/chart/ Google Charts], which would show grade statistics for the various [https://en.wikipedia.org/wiki/Rubric_(academic) rubric] grades within that assignment. The chart is interactive so the user (instructor) can toggle which rubric criteria, and which statistics, to display.

Along with displaying the rubric criteria for a single assignment, we aimed to add a feature which would allow the comparison of compatible rubric grades from two different assignments. Again, this functionality is interactive, allowing the instructor to choose which statistics will be populated in the chart.

By viewing our new visualization of rubric grades, an instructor can better judge which aspects of the course are well-understood, and which may need a bit more attention.

__TOC__

== Problem Statement ==
'''E1929 - Visualizations for Instructors''' - Class performance on specific rubrics

An interactive visualization or table that shows how a class performed on selected rubric criteria would be immensely helpful. It would show the instructor what he / she will need to focus more attention on. For example, could you create a graph showing the range and clustering of scores for the 5 main rubric criteria? And, if these same 5 criteria are used in the preliminary and final assignments, it would be nice to be able to compare performance between assignments in a visualization that showed the class results on 3 separate artifacts.

Webpage: login as instructor -> Manage -> Assignments -> View scores

=== Old Charts ===
[[File:Existing_Assignment_Grades_Wed.png|frame|centre|'''Figure 1: Existing assignment grade charts - '''The existing assignment grade charts show the average grade for the assignment and the grade distribution. During this project, we aimed to add a third chart which shows the distribution for specific rubric criteria within the assignment.]]

== Accomplished ==

=== Executed on Plans ===
We successfully executed all of the ideas we had during the planning phase:
* Add new feature to show mean and median data for rubric criteria in a given assignment
* Add new feature to show comparison
* Performed UI testing to ensure features were operational, including edge cases
* Added and ran RSpec and Capybara automated tests

=== New Charts Inserted ===
[[File:AnalyzeAssignmentWed.png|frame|centre|'''Figure 2: New Rubric Statistic Visualization - '''Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsWed.png|frame|centre|'''Figure 3: New Rubric Cross-Assignment Comparison Visualization - '''The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

=== Extra Issues Fixed ===

* Refactored [https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_team_charts.html.erb _team_charts.html.erb] partial view to use partials for each graphic. Previously both charts were defined together in _team_charts.html.erb, but now each graphic has its own partial view ([https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_team_charts_averages.html.erb _team_charts_averages.html.erb], [https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_team_charts_distribution.html.erb _team_charts_distribution.html.erb], [https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_team_charts_rubric_stats.html.erb _team_charts_rubric_stats.html.erb]). This allows more flexibility going forward, if it's decided one chart should move to a new place on the page, or to a new page.

=== Code Changes ===
[https://github.com/expertiza/expertiza/pull/1440/files Files Added/Modified]

Added: 10 + Modified: 13 = Total: 23

* app/assets/javascripts/rubric_stats.js '''(new)'''
* app/controllers/grades_controller.rb
* app/helpers/assignment_stats_helper.rb '''(new)'''
* app/models/assignment.rb
* app/models/assignment_questionnaire.rb
* app/models/assignment_stats.rb '''(new)'''
* app/models/criterion_stats.rb '''(new)'''
* app/models/question.rb
* app/models/questionnaire.rb
* app/models/review_round_stats.rb '''(new)'''
* app/models/score_view.rb
* app/views/grades/_team_charts.html.erb
* app/views/grades/_team_charts_averages.html.erb '''(new)'''
* app/views/grades/_team_charts_distribution.html.erb '''(new)'''
* app/views/grades/_team_charts_rubric_stats.html.erb '''(new)'''
* spec/controllers/grades_controller_spec.rb
* spec/factories/factories.rb
* spec/features/grade_interface_spec.rb '''(new)'''
* spec/features/helpers/grade_interface_helper.rb '''(new)'''
* spec/models/assignment_spec.rb
* spec/models/questionnaire_spec.rb

== Testing ==
We performed automated tests using RSpec Framework and Capybara. In addition, we performed manual tests of the user interface (UI), by using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, was used to verify the models of the Expertiza web application feature set. Since this feature is dealing with visualizations (charts) that are intimately tied with Active Record models, we seeded the testing database with known data via FactoryBot gem. These changes were automatically rolled-back once the testing was complete.

RSpec was used to increase/maintain automated test coverage for the methods that we added into assignment and questionnaire models. Mocks and stubs were utilized in order to decouple the model under test from dependencies of other models. This will allow us to identify easily if our model updates are causing an issue.

=== Capybara Tests ===
RSpec Capybara was used to provide integration testing of the charts. The Test Database was seeded with the appropriate information for executing the results of the charts. An additional GEM was needed, webdrivers, to utilize the predefined drivers of Selenium. The default web driver, Rack-Test, does not execute java scripts. Since the graphs that we are using require java script, thus soliciting the necessity of Selenium with its predefined web driver, selenium_chrome_headless. This provides the required functionality to process the java scripts and to automatically ensure that they exist in the DOM.

In order to use the headless web driver with the seeded Test Database, a different database strategy was required. As a result, for this test only, the database strategy was changed to truncation. Ruby 2.2.7 is used in the current version of Expertiza. This version does not allow for sharing of the database thread, and thus requires the to be written to the database outside of a transaction block. This allows for the headless web driver to see that the data is persisted the Test Database and is able to run as normal. Once the test is completed, the database tables are truncated and all data is removed.

=== UI Tests ===
In addition to the automated tests above we also performed manual testing of the newly added features to include:

* The new feature properly initializes
*# Analyze Assignment tab is loaded by default
*# Chart is in between the other two existing charts
*# Round 1, all Criteria selected, and Mean are selected by default
* Analyze Assignment tab operating correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart
* Compare Assignments tab operating correctly
*# Compare Assignments tab is only displayed if compatible assignments exist
*# Clicking Compare Assignments tab loads that tab
*# (All tests from Analyze Assignment tab apply to this tab as well)
*# The two colors for assignment comparison are correct

=== Testing Issues ===
Using the Ubuntu image, one issue was discovered was with the ScoreView view. The migration files is building the view out as a table instead of a view as required, this can be seen in the schema file. The Development database shows the ScoreView as a view, but the Test database shows it as an table. It appears that the Development database was altered outside of migrations to force the ScoreView to be a view instead of table. With this scenario, the automated integration testing was forced to seed the ScoreView as a table. Further gems are available to alleviate this issue.

== Shortcomings ==
* We were unable to find two compatible assignments in the Expertiza test database to fully test our Compare Assignments feature. We did test all the functionality using hard-coded data, but weren't able to do it pulling real data like we did for the Analyze Assignments feature.

== Decisions ==
1. Put our new chart on the View Scores page, rather than on a new page
* Since it was able to fit on the existing page while displaying all the necessary info, we figured it'd be beneficial to have all grade statistics charts together.
2. Use GoogleCharts for our new charts
* The group who previously attempted this project chose GoogleCharts because it has a high compatibility and its charts look of similar quality to those already existing in Expertiza. We agreed with this, and determined GoogleCharts had all of the features we would need.
3. Added the AssignmentStats, CriterionStats, and ReviewRoundStats models
* This was a logical, structured way to organize the various data and methods we needed.
4. Encapsulation of the data within the new models
* Since the various statistics we needed to form our chart were stored in multiple models, there would be no good place to put the new methods we'd need. The way we did it promotes cohesion, since the new classes have the sole focus of computing statistics. This also allows for future refactoring of other sporadic statistics methods.
5. Placed AssignmentStats methods in assignment_stats_helper.rb rather than in the model or controller.
* The methods of interest were really not business logic, but more like massaging of data. For that reason it belonged more in the controller than the model. However, to keep things neat and clean in the controller, the methods were moved out to the helper file.
6. The exposure of mean and median as the metric_names in grades_controller.rb
* Since we are explicitly calling the avg_data and med_data methods in the controller, we thought it made sense to name the metric_names nearby, within the controller, rather than hidden off in the helper file.
7. Moved most of the javascript code in _team_charts_rubric_stats.html.erb into app/assets/javascripts/rubric_stats.js. We had to keep our dynamic references of Ruby code in the view.
* This keeps the view more clean and concise. Also, in the previous semester, one of the reasons the team's pull request was rejected was because they had too much javascript code in their views.

== Documentation ==
[https://github.com/expertiza/expertiza/pull/1440 Pull Request]

[https://github.com/gshugh/expertiza/tree/OSS-HW4 GitHub Repo]

[https://drive.google.com/file/d/1jmOYfbNOlXQObtsK4MoIti-LsjJ_Y88P/view Demo Video]

[https://docs.google.com/document/d/1Ozw2Bj2u_LyeKUdDqAyQtz1stEIKrxkmRnwmNyUgmzw/edit#heading=h.5kwrelqdnewh Problem Statement]

== Team ==
* Akshay Ravichandran '''(Mentor)'''
* Chris Adkins
* Bobby DeMarco
* George Hugh
* John Warren

E1929 Visualizations for Instructors

2019-04-13T02:44:17Z

Gshugh: /* Project Design */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|'''Figure 1: Existing assignment grade page header - '''The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

==== Interactive Example ====

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

==== New View Examples ====

[[File:AnalyzeAssignmentNew.png|frame|centre|'''Figure 2: New Rubric Statistic Visualization - '''Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsNew.png|frame|centre|'''Figure 3: New Rubric Cross-Assignment Comparison Visualization - '''The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change controller files, view files and JavaScript files. For methods that are modified by this project, the team will also ensure that Code Climate (an automated code quality checker) issues are resolved. This project will also refactor changed methods to reflect common Ruby and Rails practices.

=== Proposed Code Changes ===
The amount of methods and files to be changed during the integration of rubric statistics and assignment grade statistics is minimal. The team proposes changing a controller file, a view file, a JavaScript file, and an RSpec files. The team does not expect to change the database nor do we expect to change the model files. Other files will be changed as required to support the integration. A preliminary list of files to be changed is given below:

[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/controllers/grades_controller.rb grades_controller.rb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/assets/javascripts/grading.js grading.js]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_participant_charts.html.erb _participant_charts.html.erb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/spec/controllers/grades_controller_spec.rb grades_controllers_spec.rb]

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|'''Figure 4: Rubric Statistic Design Flow - '''Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|'''Figure 5: Cross-Assignment Comparison Design Flow - '''Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

[http://www.highcharts.com/ Highcharts]
[http://g.raphaeljs.com/ RaphaelJS]
[http://dygraphs.com/ dygraphs]
[http://vis.stanford.edu/protovis/ Protovis]
[http://grafico.kilianvalkhof.com/ Grafico]
[https://chartkick.com/ ChartKick]
[http://www.vancharts.com/ VanCharts]
[https://developers.google.com/chart/ GoogleCharts]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-13T02:43:27Z

Gshugh: /* Proposed Code Changes */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|'''Figure 1: Existing assignment grade page header - '''The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

==== Interactive Example ====

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

==== New View Examples ====

[[File:AnalyzeAssignmentNew.png|frame|centre|'''Figure 2: New Rubric Statistic Visualization - '''Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsNew.png|frame|centre|'''Figure 3: New Rubric Cross-Assignment Comparison Visualization - '''The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change controller files, view files and JavaScript files. For methods that are modified by this project, the team will also ensure that Code Climate (an automated code quality checker) issues are resolved and refactor those methods to reflect common Ruby and Rails practices.

=== Proposed Code Changes ===
The amount of methods and files to be changed during the integration of rubric statistics and assignment grade statistics is minimal. The team proposes changing a controller file, a view file, a JavaScript file, and an RSpec files. The team does not expect to change the database nor do we expect to change the model files. Other files will be changed as required to support the integration. A preliminary list of files to be changed is given below:

[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/controllers/grades_controller.rb grades_controller.rb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/assets/javascripts/grading.js grading.js]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_participant_charts.html.erb _participant_charts.html.erb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/spec/controllers/grades_controller_spec.rb grades_controllers_spec.rb]

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|'''Figure 4: Rubric Statistic Design Flow - '''Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|'''Figure 5: Cross-Assignment Comparison Design Flow - '''Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

[http://www.highcharts.com/ Highcharts]
[http://g.raphaeljs.com/ RaphaelJS]
[http://dygraphs.com/ dygraphs]
[http://vis.stanford.edu/protovis/ Protovis]
[http://grafico.kilianvalkhof.com/ Grafico]
[https://chartkick.com/ ChartKick]
[http://www.vancharts.com/ VanCharts]
[https://developers.google.com/chart/ GoogleCharts]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-13T02:37:48Z

Gshugh: /* Tools and Design Choices */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|'''Figure 1: Existing assignment grade page header - '''The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

==== Interactive Example ====

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

==== New View Examples ====

[[File:AnalyzeAssignmentNew.png|frame|centre|'''Figure 2: New Rubric Statistic Visualization - '''Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsNew.png|frame|centre|'''Figure 3: New Rubric Cross-Assignment Comparison Visualization - '''The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change controller files, view files and JavaScript files. For methods that are modified by this project, the team will also ensure that Code Climate (an automated code quality checker) issues are resolved and refactor those methods to reflect common Ruby and Rails practices.

=== Proposed Code Changes ===
The amount of methods and files to be changed during the integration of rubric statistics and assignment grade statistics is minimal. The team proposes changing a controller file, a view file, JavaScript file, and RSpec files. The team does not expect to change the database nor do we expect to change the model files. A preliminary list of files to be changed is given below:

[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/controllers/grades_controller.rb grades_controller.rb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/assets/javascripts/grading.js grading.js]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_participant_charts.html.erb _participant_charts.html.erb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/spec/controllers/grades_controller_spec.rb grades_controllers_spec.rb]

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|'''Figure 4: Rubric Statistic Design Flow - '''Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|'''Figure 5: Cross-Assignment Comparison Design Flow - '''Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

[http://www.highcharts.com/ Highcharts]
[http://g.raphaeljs.com/ RaphaelJS]
[http://dygraphs.com/ dygraphs]
[http://vis.stanford.edu/protovis/ Protovis]
[http://grafico.kilianvalkhof.com/ Grafico]
[https://chartkick.com/ ChartKick]
[http://www.vancharts.com/ VanCharts]
[https://developers.google.com/chart/ GoogleCharts]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-13T02:33:37Z

Gshugh: /* Proposed Code Changes */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|'''Figure 1: Existing assignment grade page header - '''The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

==== Interactive Example ====

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

==== New View Examples ====

[[File:AnalyzeAssignmentNew.png|frame|centre|'''Figure 2: New Rubric Statistic Visualization - '''Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsNew.png|frame|centre|'''Figure 3: New Rubric Cross-Assignment Comparison Visualization - '''The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change controller files, view files and JavaScript files. For methods that are modified by this project, the team will also ensure that Code Climate (an automated code quality checker) issues are resolved and refactor those methods to reflect common Ruby and Rails practices.

=== Proposed Code Changes ===
The amount of methods and files to be changed during the integration of rubric statistics and assignment grade statistics is minimal. The team proposes changing a controller file, a view file, JavaScript file, and RSpec files. The team does not expect to change the database nor do we expect to change the model files. A preliminary list of files to be changed is given below:

[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/controllers/grades_controller.rb grades_controller.rb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/assets/javascripts/grading.js grading.js]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/app/views/grades/_participant_charts.html.erb _participant_charts.html.erb]
[https://github.com/gshugh/expertiza/blob/OSS-HW4/spec/controllers/grades_controller_spec.rb grades_controllers_spec.rb]

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|'''Figure 4: Rubric Statistic Design Flow - '''Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|'''Figure 5: Cross-Assignment Comparison Design Flow - '''Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

Highcharts (http://www.highcharts.com/)
RaphaelJS (http://g.raphaeljs.com/)
dygraphs (http://dygraphs.com/)
Protovis (http://vis.stanford.edu/protovis/)
Grafico (http://grafico.kilianvalkhof.com/)
ChartKick (https://chartkick.com/)
VanCharts (http://www.vancharts.com/)
GoogleCharts (https://developers.google.com/chart/)

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-13T02:19:59Z

Gshugh: /* Project Design */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|'''Figure 1: Existing assignment grade page header - '''The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

==== Interactive Example ====

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

==== New View Examples ====

[[File:AnalyzeAssignmentNew.png|frame|centre|'''Figure 2: New Rubric Statistic Visualization - '''Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsNew.png|frame|centre|'''Figure 3: New Rubric Cross-Assignment Comparison Visualization - '''The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change controller files, view files and JavaScript files. For methods that are modified by this project, the team will also ensure that Code Climate (an automated code quality checker) issues are resolved and refactor those methods to reflect common Ruby and Rails practices.

=== Proposed Code Changes ===
The amount of methods and files to be changed during the integration of rubric statistics and assignment grade statistics is minimal. The team proposes changing a controller file, a view file, JavaScript file, and RSpec files. The team does not expect to change the database nor do we expect to change the model files. A list of expected RSpec files to be changed is listed in the Test Plan. A preliminary list of files to be changed is given below:

app/controllers/grades_controller.rb
assets/javascripts/grading.js
spec/controllers/grades_controllers_spec.rb
app/views/grades/_participant_charts.html.erb

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|'''Figure 4: Rubric Statistic Design Flow - '''Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|'''Figure 5: Cross-Assignment Comparison Design Flow - '''Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

Highcharts (http://www.highcharts.com/)
RaphaelJS (http://g.raphaeljs.com/)
dygraphs (http://dygraphs.com/)
Protovis (http://vis.stanford.edu/protovis/)
Grafico (http://grafico.kilianvalkhof.com/)
ChartKick (https://chartkick.com/)
VanCharts (http://www.vancharts.com/)
GoogleCharts (https://developers.google.com/chart/)

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-13T02:02:50Z

Gshugh: /* Design Flow */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

==== Interactive Example ====

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

==== New View Examples ====

[[File:AnalyzeAssignmentNew.png|frame|centre|Figure 2: New Rubric Statistic Visualization\n Added in the center of the existing two charts is an interactive chart the instructor can use to see the mean or median scores for whichever criteria they select. This is done on the "Analyze Assignment" tab, which is selected by default when the "View Scores" page is loaded.]]

[[File:CompareAssignmentsNew.png|frame|centre|Figure 3: New Rubric Cross-Assignment Comparison Visualization\n The instructor can see a comparison between selected criteria between the current assignment and the selected assignment. The rubric criteria must be compatible in order for it to even show up in the selection list. This comparison visualization is done on the "Compare Assignments" tab which must be selected after the "View Scores" page has been loaded.]]

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change the grades_controller file, an unspecified number of files in the views/grades subdirectory, assets/javascripts/grading.js, and RSpec files. This project does not expect to change any model files, though models will be changed if model data needs to be reformatted. This project does not expect to change the database.

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|Figure 4: Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|Figure 5: Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

Highcharts (http://www.highcharts.com/)
RaphaelJS (http://g.raphaeljs.com/)
dygraphs (http://dygraphs.com/)
Protovis (http://vis.stanford.edu/protovis/)
Grafico (http://grafico.kilianvalkhof.com/)
ChartKick (https://chartkick.com/)
VanCharts (http://www.vancharts.com/)
GoogleCharts (https://developers.google.com/chart/)

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-09T00:49:44Z

Gshugh: /* Project Design */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to fine-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
During the integration of rubric statistics and assignment grade statistics, this project expects to change the grades_controller file, an unspecified number of files in the views/grades subdirectory, assets/javascripts/grading.js, and RSpec files. This project does not expect to change any model files, though models will be changed if model data needs to be reformatted. This project does not expect to change the database.

=== Design Flow ===
[[File:DesignFlowSingle.png|frame|center|Figure 2: Instructor wants to view student scores on individual rubric criteria.]]

[[File:DesignFlowCompare.png|frame|center|Figure 3: Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments.]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries are given below:

Highcharts (http://www.highcharts.com/)
RaphaelJS (http://g.raphaeljs.com/)
dygraphs (http://dygraphs.com/)
Protovis (http://vis.stanford.edu/protovis/)
Grafico (http://grafico.kilianvalkhof.com/)
ChartKick (https://chartkick.com/)
VanCharts (http://www.vancharts.com/)
GoogleCharts (https://developers.google.com/chart/)

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T17:11:40Z

Gshugh: /* Introduction */

== Introduction ==
It is the desire of all instructors to emphasize course material that students have trouble understanding and de-emphasize those aspects of the course material which students readily grasp. One method used by instructors is the creation of questionnaires, or rubrics. A rubric consists of a number of questions, or criterion, that give instructors a glimpse into student understanding of course materials. Use of rubrics and their association with a course assignment allow instructors to find-tune their lesson plans to their students' understanding.

Creation of assignments, and their associated rubrics, can be a daunting task that can be made easier through the use of online platforms. Expertiza is one such online assignment grading platform. Within Expertiza, instructors create courses and assignments. For each assignment, instructors create one or more peer review rubrics for students to complete. After each round of rubrics, students can submit changes to their assignment based on these rubrics, with each submission and rubric considered a round. Hence, assignments have multiple rounds with each round associated with a rubric.

Instructors use the association between the assignment and the submitted rubric(s) associated with the assignment to understand what subjects need more focus. For example, a low average score on a rubric's particular question, or criterion, can indicate that the class has issues with a particular part of the assignment. Currently, instructors using Expertiza display assignment scores on one pages, but need to visit a completely separate page to display rubric scores. This separation of information hinders the instructor's ability to fully comprehend the associations between the assignment scores and the rubric scores. This, in turn, minimizes the likelihood that instructors will integrate this information to fine-tune their course material.

This project proposes to overcome this weakness in Expertiza by integrating the display of assignment scores and rubric scores onto a single page. This integration will allow instructors to more easily associate low rubric average scores with assignment scores. The ability to visualize assignment scores and rubric scores in a single location will reduce the workload on instructors when the scores. This, in turn, will increase the likelihood that instructors will change their lesson plans to reflect the students' understanding of the course material.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
This project expects to change controller files, view files, JavaScript files, and RSpec files. This project does not expect to change any model files, though models will be changed if model data needs to be reformatted. This project does not expect to change the database.

=== Design Flow ===
Instructor wants to view student scores on individual rubric criteria:

[[File:DesignFlowSingle.png]]

Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments:

[[File:DesignFlowCompare.png]]

=== Tools and Design Choices ===
This project proposes using a third party JavaScript library for rendering the rubric statistics. This project proposes two requirements for the visualization library. The first requirement is to use a visualization library that performs client-side rendering. Using a client-side rendering library will minimize the number of server interactions as the instructor changes which rubric statistics to display. This minimization of server interaction will maximize the response time of Expertiza.

The second requirement for the visualization library is compatibility with current Expertiza graphics. The compatibility requirement implies that the visualization library is one that is already being used in Expertiza or a visualization library that could be used to render the current graphics.

Examples of client-side visualization libraries is given below:

Highcharts (http://www.highcharts.com/)
RaphaelJS (http://g.raphaeljs.com/)
dygraphs (http://dygraphs.com/)
Protovis (http://vis.stanford.edu/protovis/)
Grafico (http://grafico.kilianvalkhof.com/)
ChartKick (https://chartkick.com/)
VanCharts (http://www.vancharts.com/)
GoogleCharts (https://developers.google.com/chart/)

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===

=== UI Tests ===

E1929 Visualizations for Instructors

2019-04-08T16:43:46Z

Gshugh: /* Introduction */

E1929 Visualizations for Instructors

2019-04-08T16:35:05Z

Gshugh: /* Introduction */

E1929 Visualizations for Instructors

2019-04-08T15:02:24Z

Gshugh: /* Tools and Design Choices */

E1929 Visualizations for Instructors

2019-04-08T14:59:38Z

Gshugh: /* Tools and Design Choice */

E1929 Visualizations for Instructors

2019-04-08T11:31:19Z

Gshugh: /* Test Results */

E1929 Visualizations for Instructors

2019-04-08T11:30:34Z

Gshugh: /* Files Involved */

E1929 Visualizations for Instructors

2019-04-08T11:29:35Z

Gshugh: /* Project Design */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
This project expects to change controller files, view files, JavaScript files, and RSpec files. This project does not expect to change any model files, though models will be changed if model data needs to be reformatted. This project does not expect to change the database.

=== Design Flow ===
Instructor wants to view student scores on individual rubric criteria:

[[File:DesignFlowSingle.png]]

Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments:

[[File:DesignFlowCompare.png]]

=== Tools and Design Choice ===
This project proposes using a third party library for displaying the rubric statistics. The criteria for this third party library will include TBS.

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T11:26:13Z

Gshugh: /* Project Design */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
This project expects to change controller files, view files, JavaScript files, and RSpec files. This project does not expect to change any model files, though models will be changed if model data needs to be reformatted. This project does not expect to change the database.

=== Design Flow ===
Instructor wants to view student scores on individual rubric criteria:

[[File:DesignFlowSingle.png]]

Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments:

[[File:DesignFlowCompare.png]]

=== Tools and Design Choice ===
This project proposes using a third party library for displaying the rubric statistics. The criteria for this third party library will include TBS.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T11:21:13Z

Gshugh: /* Project Design */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
Instructor wants to view student scores on individual rubric criteria:

[[File:DesignFlowSingle.png]]

Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments:

[[File:DesignFlowCompare.png]]

=== Tools and Design Choice ===
This project proposes using a third party library for displaying the rubric statistics. The criteria for this third party library will include TBS.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T11:14:16Z

Gshugh: /* Proposed Changes */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project integrate rubric statistics to the above assignment grade view. Rubric statistic integration into the assignment grade view allow two types of visualizations. The first visualization allows the instructor to display rubric statistics within a single assignment. The second visualization allows the instructor to display rubric statistics between different assignments in the same course.

=== Proposed Assignment Grade Visualization ===

This project proposes the integration of rubric statistic visualization for both single assignments and multiple assignments into the assignment grade view. The integration occurs with a single change to the header of the assignment grade view, and retains the list of student grades. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
Instructor wants to view student scores on individual rubric criteria:

[[File:DesignFlowSingle.png]]

Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments:

[[File:DesignFlowCompare.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T10:58:43Z

Gshugh: /* Proposed Changes */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

=== Existing Views ===

In both cases, the project will add rubric statistics to the assignment grade view. The current assignment grade view consists of a header containing grade statistics followed by a table of the individual grades. In the assignment grade view header, the left side fo the header shows the average assignment grade as a circle, while the right side of the assignment grade view header shows the assignment grade distribution. Figure 1 shows the current header in the grade assignment view page.

[[File:Existing_Assignment_Grades.JPG|frame|centre|Figure 1: Existing assignment grade page header. The existing assignment grade page header has both the average grade for the assignment and the grade distribution for the assignment. The left side shows the average as the percentage of a circle. The right side of the header shows the grade distribution for the assignment. The grade distribution shows the minimum and maximum grade for the assignment. Under the header is a list of the grades for each student.]]

The changes proposed by this project add rubric statistics to this assignment grade view. This project proposes to integrate rubric statistics visualization within a single assignment and to integrate rubric statistics visualization between multiple assignments.

=== Proposed Changes for Single Assignment ===

The first visualization change proposed by this project is the integration of rubric statistic visualization within a single assignment. The rubric statistics are integrated into the assignment grade view header. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/single.html

The rubric statistics are shown in the upper middle section of the header, while the options used to filter out the statistics are shown in the lower middle section of the header. The left and right side of the header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consists of five criteria, while the rubric in round 2 consists of 4 criteria. The drop-down menu on the left side selects the round of interest. The radio buttons next to each criterion selects the bar graphs shown. The bar graphs represent the percentage score of the selected criterion. Finally, the drop-down menu on the right side selects the statistic shown. This project proposes that the rubric statistic be limited to either the mean of the score or the median of the score. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

=== Proposed Changes for Multiple Assignments ===

Along with the integration of the rubric statistics within a single assignment, this project also proposes integrating rubric statistic visualizations between multiple assignments. The rubric statistics are integrated into the assignment grade view header. The following HTML mock-up shows the proposed changes to the header. The list of student grades is not changed and therefore not shown.

https://jwarren3.github.io/expertiza/tabs.html

The upper part of the rubric statistic visualization displays a set of tabs that allow the instructor to analyze the rubric within a single assignment or to compare the rubric statistics between multiple assignments. The middle part of the rubric statistic visualization displays the statistics for each selected criteria as a bar graph. The heights of the bars are shown as a percentage of the maximum value for each criteria. The bottom part of the rubric statistic visualization displays a set of options that allow the instructor to filter the statistics shown in the bar graph. The left side (assignment average) and right side (assignment distribution) of the assignment grade view header are not changed.

In the integration of the rubric statistic visualization mock-up within a single assignment, there are two rounds of rubrics for the students to fill out. The rubric in round 1 consisted of five criteria, while the rubric in round 2 consisted of 4 criteria. The round of interest is selected using the drop-down menu on the left side. The criteria shown in the bar graph are selected using radio buttons next to each criterion. Finally, the type of statistic shown is selected using a drop-down menu on the right side of the options. Currently, the statistic is limited to either mean or median. Hovering the mouse over each of the bars in the bar graph shows the numerical value of the chosen statistic.

Visualizing the rubric statistics within a single assignment starts by selecting the left tab titled "Analyze Assignment". The default displays the mean of all criteria from the first round. Changing the round, the type of statistic, and the particular criteria are controlled from the drop-down menus and radio buttons below the bar graph.

Visualizing the rubric statistics between assignments starts by selecting the right tab titled "Compare Assignments". The default displays the comparisons between round one and all criteria of an assignment in the same course. The default assignment is the chronologically earliest assignment. The current assignment is shown in red while the rubric being compared is shown in blue.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
Instructor wants to view student scores on individual rubric criteria:

[[File:DesignFlowSingle.png]]

Instructor wants to compare student scores on individual rubric criteria between two compatible rounds of two different assignments:

[[File:DesignFlowCompare.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

File:Existing Assignment Grades.JPG

2019-04-08T02:49:49Z

Gshugh:

E1929 Visualizations for Instructors

2019-04-08T02:06:10Z

Gshugh: /* Existing View and Proposed Changes */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Existing Views and Proposed Changes ==
To help instructors understand the relationship between assignment scores and rubric scores, this project proposes two types of visualizations. The first type of visualization allows instructors to examine the rubric statistics for a single assignment. The second type of visualization allows instructors to compare the rubric statistics between two different assignments when the criteria for each assignment is the same.

Visualizing the rubric statistics for a single assignment is accomplished by adding the rubric statistics to the assignment grade view.

https://jwarren3.github.io/expertiza/single.html

The visualizations are divided into two separate features. The first feature displays a statistic for each criteria in a given assignment rubric. Currently, the view only displays the overall average and a distribution of the scores from each student. This project adds the mean (or median) for each criteria within the chosen rubric.

The second feature of the project is ability to visualize different rubric criteria for different assignments in the same course.
The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T01:43:29Z

Gshugh: /* Introduction */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
The visualizations are divided into two separate features. The first feature displays a statistic for each criteria in a given assignment rubric. Currently, the view only displays the overall average and a distribution of the scores from each student. This project adds the mean (or median) for each criteria within the chosen rubric.

The second feature of the project is ability to visualize different rubric criteria for different assignments in the same course.
The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T01:43:17Z

Gshugh: /* Introduction */

== Introduction ==
Expertiza is an online, assignment, grading platform for courses associated with instructors. Each instructor creates courses and assignments associated with those courses. For each assignment, students peer review other students' assignments via questionnaires or rubrics. After each round of rubrics, students can submit changes to their assignment based on these rubrics. Each submission and rubric is considered a round. Hence, assignments have multiple rounds each associated with a rubric.

Instructors use the association between the assignment and the rubrics to understand what subjects need more focus. For example, a low average on a particular question, or criterion, on a rubric can indicate that the class has issues with a particular part of the assignment. Currently, the information about assignment grades is on one pages, while the information on rubrics is on a second page. This project intends to make the visualization of assignment grades and rubric scores easier by showing rubric statistics on the assignment grade page.

__TOC__

== Proposed Changes ==
The visualizations are divided into two separate features. The first feature displays a statistic for each criteria in a given assignment rubric. Currently, the view only displays the overall average and a distribution of the scores from each student. This project adds the mean (or median) for each criteria within the chosen rubric.

The second feature of the project is ability to visualize different rubric criteria for different assignments in the same course.
The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-08T00:18:23Z

Gshugh: /* Introduction */

== Introduction ==
Expertiza is an online assignment grading platform for courses associated with instructors. Each instructor can create a course. Within each course instructors create assignments and within each assignment, instructors can create review rounds. During each round, the instructor designs a rubric so that students can review. Instructors can create assignments and implement peer reviews for submitted assignments. This project concerns the creation of a system for visualizing student performance on those assignments, primarily as graded in peer reviews. Graphs will be made to show various rubric criteria and the class' performance on the criteria. If the criteria are the same for multiple stages of review, an instructor should be able to compare performance over time or between reviews. Our task is to provide an interactive visualization or a table for instructors that shows how their class performed on selected rubric criteria. Such feature would be immensely helpful for instructors as it would assist them to identify what they need to focus more attention on. For example, creating a graph showing the average scores for all or a certain subset of main rubric criteria (questionnaire). If the average score of the class on selected criteria (question) is low means the instructor can emphasize more on the learning materials related to it.

__TOC__

== Proposed Changes ==
The visualizations are divided into two separate features. The first feature displays a statistic for each criteria in a given assignment rubric. Currently, the view only displays the overall average and a distribution of the scores from each student. This project adds the mean (or median) for each criteria within the chosen rubric.

The second feature of the project is ability to visualize different rubric criteria for different assignments in the same course.
The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-07T23:26:48Z

Gshugh: /* Proposed Changes */

== Introduction ==
Expertiza is an online assignment grading platform. Instructors can create assignments and implement peer reviews for submitted assignments. This project concerns the creation of a system for visualizing student performance on those assignments, primarily as graded in peer reviews. Graphs will be made to show various rubric criteria and the class' performance on the criteria. If the criteria are the same for multiple stages of review, an instructor should be able to compare performance over time or between reviews. Our task is to provide an interactive visualization or a table for instructors that shows how their class performed on selected rubric criteria. Such feature would be immensely helpful for instructors as it would assist them to identify what they need to focus more attention on. For example, creating a graph showing the average scores for all or a certain subset of main rubric criteria (questionnaire). If the average score of the class on selected criteria (question) is low means the instructor can emphasize more on the learning materials related to it.

__TOC__

== Proposed Changes ==
The visualizations are divided into two separate features. The first feature displays a statistic for each criteria in a given assignment rubric. Currently, the view only displays the overall average and a distribution of the scores from each student. This project adds the mean (or median) for each criteria within the chosen rubric.

The second feature of the project is ability to visualize different rubric criteria for different assignments in the same course.
The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-07T21:48:29Z

Gshugh: /* Proposed Changes */

== Introduction ==
Expertiza is an online assignment grading platform. Instructors can create assignments and implement peer reviews for submitted assignments. This project concerns the creation of a system for visualizing student performance on those assignments, primarily as graded in peer reviews. Graphs will be made to show various rubric criteria and the class' performance on the criteria. If the criteria are the same for multiple stages of review, an instructor should be able to compare performance over time or between reviews. Our task is to provide an interactive visualization or a table for instructors that shows how their class performed on selected rubric criteria. Such feature would be immensely helpful for instructors as it would assist them to identify what they need to focus more attention on. For example, creating a graph showing the average scores for all or a certain subset of main rubric criteria (questionnaire). If the average score of the class on selected criteria (question) is low means the instructor can emphasize more on the learning materials related to it.

__TOC__

== Proposed Changes ==
The visualizations are divided into two separate features. The first feature displays a statistic for each criteria in a given assignment rubric. Currently, the view only displays the overall average and a distribution of the scores from each student. This project adds the mean (or median) for each criteria within the chosen rubric.

The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests using frameworks RSpec and Capybara. In addition, we will perform manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
The RSpec Testing Framework, automated testing, will be used to verify the Models of the Expertiza Rails Web application feature set. Since this feature is dealing with Visualizations (charts) that is intimately tied with an Active Record Models, we will seed the Testing Database with known data via RSpec. These changes will be automatically rolled-back once the testing is complete.

=== Capybara Tests ===
Another automated testing framework that will be used is Capybara. Capybara is an browser type test to simulate a user clicking through your site. We will use this testing framework to verify that our charting object is present on the page and contains the seeded data that we had loaded.

=== UI Tests ===
In addition to the automated tests above we will also perform manual testing of the newly added features to include:

* Chart is displaying correctly
*# Bars are showing up where expected
*# Bar annotations are showing the expected value
*# Criteria labels are for the correct bar and displaying correct values
*# Hover text is displaying the correct values
*# Null values are not present on the chart
*# Correct colors are used for the multi-round view
* Show Labels checkbox works as expected
* Round Criteria is displaying correctly
*# Round dropdown menu shows all rounds for the assignment
*# Selecting a round changes the criteria checkboxes
*# All checkboxes are displayed with appropriate text
*# Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-04T17:44:39Z

Gshugh:

== Introduction ==
Expertiza is an online assignment grading platform. Instructors can create assignments and implement peer reviews for submitted assignments. This project concerns the creation of a system for visualizing student performance on those assignments, primarily as graded in peer reviews. Graphs will be made to show various rubric criteria and the class' performance on the criteria. If the criteria are the same for multiple stages of review, an instructor should be able to compare performance over time or between reviews. Our task is to provide an interactive visualization or a table for instructors that shows how their class performed on selected rubric criteria. Such feature would be immensely helpful for instructors as it would assist them to identify what they need to focus more attention on. For example, creating a graph showing the average scores for all or a certain subset of main rubric criteria (questionnaire). If the average score of the class on selected criteria (question) is low means the instructor can emphasize more on the learning materials related to it.

__TOC__

== Proposed Changes ==
The visualizations will be implemented as either a single or stacked bar chart with a bar for each of the selected criteria to be observed. If a single bar, then the height of the bar will be the total class average, but a stacked bar chart may be better to show the percentage of the class that received each score.

1. On clicking Manage and then on assignments, following page appears.

2. Click on 'view score' icon of an assignment. The summary report page of the selected assignment comes up.

3. Following are mockup screens which we wish to create:

a) Instructor would select the round and rubric criteria of the assignment for which he/she wants to view the class performance.

b) The bar graph of the class performance for those criteria would be displayed.

== Project Design ==
The changes made to the expertiza project will primarily include HTML/ERB changes to the view files to accommodate the added charts on the page and the necessary javascript to allow responsive design. Brief controller modifications will be made to facilitate database filtering to get the displayed data.

=== Design Flow ===
The flowchart representing graphical flow of an instructor visiting view scores under assignments is given below:

[[File:A3.png]]

=== Tools and Design Choice ===
We have used the lightweight [https://developers.google.com/chart/ Google Charts] library for displaying the chart data on the page, with standard HTML for all of the options and dropdowns for option selection. Google Charts was chosen because of its high compatibility, full option set, and comparable graphical quality to the rest of expertiza while keeping a small JS footprint, which should help prevent slow page responsiveness.

=== Visualization ===
The following graph shows the view of the 'view scores' page after the modifications. The instructor selects a subset of rubric criteria for which he/she wants to know how a class performed for a particular round. A bar graph of the average score of the class for that subset of criteria is displayed.

The above graph shows an average score of the class for 10 rubric criteria in Round 1 for assignment "OSS project/Writing assignment 2" selected by the instructor. A live demo with randomly generated data can be found on [https://jsfiddle.net/Jereman/5uxqr92y/ JSFiddle]

== Test Plan ==
The team plans to perform both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app.

=== RSpec Framework Tests ===
Automated tests, using the RSpec framework, will be run against our project changes. Both test-driven development (TDD) and behavior-driven development (BDD) will be used during the project. For each existing model/controller that is changed in the project, the team will ensure that existing unit/integration test specs still pass and create additional tests to ensure that new functionality is working correctly. For each new model/controller, the team will create new unit/integration tests and ensure both 100% code coverage and complete testing of functionality.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

== Files Involved ==
We have implemented a new partial file criteria_charts to the team_chart that display the bar graph with existing data collected by the grades controller methods to the view page.

Modified files:
<div style="display: inline-block">
<pre>
app/controllers/grades_controller.rb

app/views/grades/_teams.html.erb

app/views/grades/_criteria_charts.html.erb

app/views/grades/_team_charts.html.erb
</pre>
</div>

=== app/views/grades/_criteria_charts.html.erb ===
<html>
<head>
<%= content_tag :div, class: "chartdata_information", data: {chartdata: @chartdata} do %>
<% end %>
<%= content_tag :div, class: "text_information", data: {text: @text} do %>
<% end %>
<%= content_tag :div, class: "minmax_information", data: {minmax: @minmax} do %>
<% end %>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {packages: ['corechart', 'bar']});
//Display Options
var showLabels = true;
var barColors = [ // Other colors generated from the expertiza base red
'#A90201', // using paletton.com
'#018701',
'#016565',
'#A94D01'
];
function getData(){ //Loads all chart data from the page
chartData = $('.chartdata_information').data('chartdata');
chartText = $('.text_information').data('text');
chartRange = $('.minmax_information').data('minmax');
for (var i = 0; i < chartData.length; i++){ //Set all the criteriaSelected to true
var criteria = [];
for (var j = 0; j < chartData[i].length; j++){
criteria.push(true);
}
criteriaSelected.push(criteria);
}
}
function generateData() { //Generates random data for testing
var rounds = 3;
for(var i = 0; i < rounds; i++) {
var criteriaNum = Math.floor(Math.random() * 5 + 5); //Random number of criteria
var round = [];
var criteria = [];
for(var j = 0; j < criteriaNum; j++) {
round.push(Math.floor(Math.random() * 101)); //Random score for each criterion
criteria.push(true); //Everything starts out true
}
chartData.push(round);
criteriaSelected.push(criteria);

chartOptions = { //Render options for the chart
title: 'Class Average on Criteria',
titleTextStyle: {
fontName: 'arial',
fontSize: 18,
italic: false,
bold: true
chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
var checkBox = document.getElementById("labelCheck");
checkBox.checked = true;
checkBox.style.display = "inline";
updateChart(currentRound);
loadRounds(); }
function updateChart(roundNum) { //Updates the chart with a new round number and renders
currentRound = roundNum;
renderChart();
loadCriteria();
function renderChart() { //Renders the chart if changes have been made
var data = loadData();
chartOptions.vAxis.viewWindow.max = 5;
chartOptions.vAxis.viewWindow.min = 0;
if (chartRange[currentRound]) { //Set axis ranges if they exist
if (chartRange[currentRound][1])
chartOptions.vAxis.viewWindow.max = chartRange[currentRound][1];
if (chartRange[currentRound][0])
chartOptions.vAxis.viewWindow.min = chartRange[currentRound][0];
}
chart.draw(data, chartOptions);
}

chartOptions.hAxis.ticks = [];
var rowCount = 1;
for(var i = 0; i < chartData[currentRound].length; i++) { //Add a chart row for each criterion if not null
if (criteriaSelected[currentRound][i] && chartData[currentRound][i]) {
data.addRow([rowCount, chartData[currentRound][i], barColors[0], (showLabels) ? chartData[currentRound][i].toFixed(1).toString() : ""]);
chartOptions.hAxis.ticks.push({v: rowCount++, f: (i+1).toString()});
}
}

var data = new google.visualization.DataTable();
data.addColumn('number', 'Criterion');
var i;
for(i = 0; i < roundNum; i++) { //Add all columns for the data
data.addColumn('number', 'Round ' + (i+1).toString());
data.addColumn({type: 'string', role: 'style'}); //column for specifying the bar color
data.addColumn({type: 'string', role: 'annotation'});

var newRow = [];
var elementsAdded = false;
newRow.push(rowCount);
for(var j = 0; j < roundNum; j++) { //If the round has the criterion, add it
if (chartData[j][i]) {
newRow.push(chartData[j][i]);
elementsAdded = true;
} else {
newRow.push(null);
}
newRow.push(barColors[j % barColors.length]); //Add column color
if (chartData[j] && chartData[j][i] && showLabels)
newRow.push(chartData[j][i].toFixed(1).toString()); //Add column annotations
else
newRow.push("");
}
function loadCriteria() { //Creates the criteria check boxes
var form = document.getElementById("chartCriteria");
while (form.firstChild) //Clear out the old check boxes
form.removeChild(form.firstChild);
if (currentRound == -1) //Don't show criteria for 'all rounds'
return;
chartData[currentRound].forEach(function(dat, i) {
var checkbox = document.createElement('input');
checkbox.type = "checkbox";
checkbox.id = "checkboxoption" + i;
checkbox.onclick = function() { //Register callback to toggle the criterion
checkboxUpdate(i);
}
var label = document.createElement('label')

<form id="chartOptions" name="chartOptions">
<select id="chartRounds" name="rounds"
onChange="updateChart(document.chartOptions.chartRounds.options[document.chartOptions.chartRounds.options.selectedIndex].value)" style = "display: none">
</select>
<label><input type="checkbox" id = "labelCheck" checked="checked" style="display: none" onclick="showLabels = !showLabels; renderChart();">Show
Labels</label>
</form>
<div id="chartCriteria" name="chartCriteria">
</div>

=== app/controllers/grades_controller.rb ===

def action_allowed?
case params[:action]
when 'view_my_scores'
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator',
'Student'].include? current_role_name and
are_needed_authorizations_present?(params[:id], "reader", "reviewer") and
check_self_review_status
when 'view_team'
if ['Student'].include? current_role_name # students can only see the head map for their own team
participant = AssignmentParticipant.find(params[:id])
session[:user].id == participant.user_id
else
true
end
else
['Instructor',
'Teaching Assistant',
'Administrator',
'Super-Administrator'].include? current_role_name
end
end
# collects the question text for display on the chart
# Added as part of E1859
def assign_chart_text
@text = []
(1..@assignment.num_review_rounds).to_a.each do |round|
question = @questions[('review' + round.to_s).to_sym]
@text[round - 1] = []
next if question.nil?
(0..(question.length - 1)).to_a.each do |q|
@text[round - 1][q] = question[q].txt
end
end
end

# find the maximum and minimum scores for each questionnaire round
# Added as part of E1859
def assign_minmax(questionnaires)
@minmax = []
questionnaires.each do |questionnaire|
next if questionnaire.symbol != :review
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
next if round.nil?
@minmax[round - 1] = []
@minmax[round - 1][0] = if !questionnaire.min_question_score.nil? and questionnaire.min_question_score < 0
questionnaire.min_question_score
else
0
end
@minmax[round - 1][1] = if !questionnaire.max_question_score.nil?
questionnaire.max_question_score
else
5
end
end
end
# this method collects and averages all the review scores across teams
# Added as part of E1859
def assign_chart_data
@rounds = @assignment.num_review_rounds
@chartdata = []
(1..@rounds).to_a.each do |round|
@teams = AssignmentTeam.where(parent_id: @assignment.id)
@teamids = []
@result = []
@responseids = []
@scoreviews = []
(0..(@teams.length - 1)).to_a.each do |t|
@teamids[t] = @teams[t].id
@result[t] = ResponseMap.find_by_sql ["SELECT id FROM response_maps
WHERE type = 'ReviewResponseMap' AND reviewee_id = ?", @teamids[t]]
@responseids[t] = []
@scoreviews[t] = []
(0..(@result[t].length - 1)).to_a.each do |r|
@responseids[t][r] = Response.find_by_sql ["SELECT id FROM responses
WHERE round = ? AND map_id = ?", round, @result[t][r]]
@scoreviews[t][r] = Answer.where(response_id: @responseids[t][r][0]) unless @responseids[t][r].empty?
end
end
@chartdata[round - 1] = []
# because the nth first elements could be nil
# iterate until a non-nil value is found or move to next round
t = 0
r = 0
t += 1 while @scoreviews[t].nil?
while t < @scoreviews.length and @scoreviews[t][r].nil?
if r < @scoreviews[t].length - 1
r += 1
else
def assign_chart_data
end
end
next if t >= @scoreviews.length
(0..(@scoreviews[t][r].length - 1)).to_a.each do |q|
sum = 0
counter = 0
def retrieve_questions(questionnaires)
questionnaires.each do |questionnaire|
round = AssignmentQuestionnaire.where(assignment_id: @assignment.id, questionnaire_id: questionnaire.id).first.used_in_round
questionnaire_symbol = if !round.nil?
(questionnaire.symbol.to_s + round.to_s).to_sym
else
questionnaire.symbol
end
@questions[questionnaire_symbol] = questionnaire.questions
end
end
def update
if format("%.2f", total_score) != params[:participant][:grade]
participant.update_attribute(:grade, params[:participant][:grade])
message = if participant.grade.nil?
"The computed score will be used for " + participant.user.name + "."
else
"A score of " + params[:participant][:grade] + "% has been saved for " + participant.user.name + "."
end
end
flash[:note] = message
redirect_to action: 'edit', id: params[:id]

=== app/views/grades/_team_charts.html.erb ===
<pre>
<br> <br>
<%= render :partial => 'criteria_charts' %>
<br>

<a href="#" name='team-chartLink' onClick="toggleElement('team-chart', 'stats');return false;">Hide stats</a>
<br>
<TR style ="background-color: white;" class="team" id="team-chart">
<th>

<div class="circle" id="average-score">

</div>
Class Average
</th>
<TH COLSPAN="8">
<img src="<%= @average_chart %>" ><br>
Class Distribution
<br>
</th>
<TH WIDTH="9"> </th>
</TR>

<script type="text/javascript">
var myCircle = Circles.create({
id: 'average-score',
radius: 50,
value: <%= @avg_of_avg.to_i %>,
maxValue: 100,
width: 15,
text: '<%=@avg_of_avg.to_i%>',
colors: ['#FFEB99', '#FFCC00'],
duration: 700,
textClass: 'circles-final'
});
</script>

<style>
.circles-final{
font-size: 16px !important;
}
</style>
</pre>

== Test Results ==
The team ran both automated tests, using the RSpec framework, and manual tests of the user interface (UI), using the app. The automated tests helped to ensure that the basic functionality of the app still worked, while the UI tests ensured that the visualizations were correct.

=== RSpec Test Results ===
In order to ensure that our changes did not affect basic functionality of the app, we made sure that all tests that passed before our changes also passed after our changes. Add statistics on the tests before our changes and matching statistics after our changes.

=== UI Tests ===
To validate all functionality of the chart when adding new features or fixing old ones, the following criteria were tested manually for expected functionality:

# Chart is displaying correctly
## Bars are showing up where expected
## Bar annotations are showing the expected value
## Criteria labels are for the correct bar and displaying correct values
## Hover text is displaying the correct values
## Null values are not present on the chart
## Correct colors are used for the multi-round view
# Show Labels checkbox works as expected
# Round Criteria is displaying correctly
## Round dropdown menu shows all rounds for the assignment
## Selecting a round changes the criteria checkboxes
## All checkboxes are displayed with appropriate text
## Checkboxes correctly remove or add criterion bars to the chart

E1929 Visualizations for Instructors

2019-04-04T13:57:27Z

Gshugh: Created page with "Place Holder for our write-up"

Place Holder for our write-up

E1920 Fix Code Climate Issues

2019-04-01T21:19:48Z

Gshugh: /* New RSpec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.

Randomized with seed 29018
.........

Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending

Randomized with seed 29018

Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

We ran this command against master branch as a baseline, which produced the following results:

817 examples, 0 failure, 16 pending

These tests represented 1510 lines of code and 58.54% code coverage for our models. Among our models, these numbers included 10 models that had 100% code coverage.

However, while working with the existing RSpec tests, we noticed that some models have relatively low coverage (> 40%). Therefore, we could not rely strictly on existing RSpec tests and guarantee correctness of our code changes by running them. We decided to write additional Rspec tests that directly test all our code changes and add them into existing spec files by modifying existing tests and boost the test coverage on files that we modified. For example, we fixed multiple Code Climate issues in the [https://github.com/gshugh/expertiza/commit/b9aac55b6eb331c1db295b7e7dd45fbbdba19abc app/models/team.rb] file. Specifically, complications of such issues as "Use a guard clause instead of wrapping the code inside a conditional expression", "Use ''find_by'' instead of ''where.first''", and others were resolved in ''import'', ''export'', and ''handle_duplicate'' method calls. Most of the changes are listed below:

[[File: app_models_teams_1.png]]
[[File: app_models_teams_2.png]]

Any of the above changes may break existing functionality of the code without proper testing. Moreover, we noticed that existing ''spec/models/team_spec.rb'' Rspec file does not thoroughly tests these method calls and had very a little to none of such tests. Hence, in order to verify and test all our changes, we wrote additional Rspec tests and added them into ''spec/models/team_spec.rb'' that specifically tests our code changes. ''Note'' that in the following test cases, we cover all possible scenarios, including edge-case scenarios. Check out [https://github.com/gshugh/expertiza/commit/96cec7fa82c1c55e31e0196d3a025111a4fe134a spec/models/team_spec.rb] for full list of Rspec tests. The following is a list of Rspec we developed to test all our changes in the ''app/models/team.rb'' file:

[[File: rspec_models_team_spec_1.png]]
[[File: rspec_models_team_spec_2.png]]
[[File: rspec_models_team_spec_3.png]]

''Note'' that this is only one small example we show here of additional Rspec tests we developed. Full list of newly developed and added Rspec tests can be found in our Git Pull Request. Also note that by adding new spec test cases, we increased test code coverage on all of the models. The test coverage for the ''app/models/team.rb'' model was increased up to 88.51% as follows:

[[File: spec_models_team_spec_test_coverage.png]]

=== New RSpec Testing ===

Moreover, while working with the existing Rspec tests, besides low coverage on some of the tests, we also noticed that some models are tested indirectly via other Rspec tests. Meaning there is no dedicated spec test file for some of the models that we fixed. Since we were not aware of what spec files are responsible for testing some models that have no dedicated spec test file, we did not know what are the exact set of test cases existing Rspec testing framework runs on these file (e.g. edge-case scenarios and etc). Similarly, as with existing Rspec tests we found out that existing specs would not suffice for the changes that we made. Therefore, we created '''new''' dedicated Rspec test files and wrote test cases that test our changes directly.

For example, we fixed multiple Code Climate issues in the ''app/models/teams_user.rb'' file. At the moment, there is no corresponding Rspec file for that model in the system. Therefore, we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to test directly our code changes and boost the code coverage on that model. The following is the change that we did in the ''app/models/teams_user.rb'' file:

[[File: app_models_teams_user_changes.png]]

The following is newly created corresponding ''spec/models/teams_test_spec.rb'' test file included in our Git Pull Request having all general-purpose tests in it as follows:

[[File: spec_models_teams_user_1.png]]
[[File: spec_models_teams_user_2.png]]
[[File: spec_models_teams_user_3.png]]

''Note'' that by creating new corresponding spec test for the ''app/models/teams_user.rb'' model, we achieved 100% test coverage on that model, whereas before it was around 60.53%.

[[File: spec_models_teams_user_test_coverage.png]]

Again this is only one example we show here of the files that we created. More additional spec files were created to test our code changes. For example, we made extensive changes by fixing "Tagging a string as html safe may be a security risk" Code Climate issue. Most of those models did not have corresponding Rspec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment. The test coverage on those models was also increased.

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

This represented 1440 lines of code and 68.19% of code coverage for the models of interest. The number of lines of code decreased by 4.64% (from 1510 to 1440), an increase in code coverage of 16.48% (from 58.54% to 68.19%) and an increase in test examples of 8.45% (from 817 to 886). Included in the new test numbers was a 70% increase in the number of models that had 100% coverage (from 10 to 17). The increase in the percentage of code coverage was due to a combination of the decrease in the number of lines and the increase in the number of test examples.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])! There are no more Code Climate issues found!

Although, in our project we were not asked to write additional Rspec tests, we dedicated some of our time to do so. The goal of writing additional spec test cases was to validate our code changes, make sure our changes did not cause any problems in the app, and boost the test coverage on the models we worked on. We achieved all our goals and tested all our changes with the help of Rspec tests that we wrote. We also ensured that our additional spec tests boost the code coverage.

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage on all of the existing files by writing more Rspec tests and considering more possible scenarios (i.e, edge-case scenarios).

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T21:17:10Z

Gshugh: /* Existing Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.

Randomized with seed 29018
.........

Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending

Randomized with seed 29018

Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

We ran this command against master branch as a baseline, which produced the following results:

817 examples, 0 failure, 16 pending

These tests represented 1510 lines of code and 58.54% code coverage for our models. Among our models, these numbers included 10 models that had 100% code coverage.

However, while working with the existing RSpec tests, we noticed that some models have relatively low coverage (> 40%). Therefore, we could not rely strictly on existing RSpec tests and guarantee correctness of our code changes by running them. We decided to write additional Rspec tests that directly test all our code changes and add them into existing spec files by modifying existing tests and boost the test coverage on files that we modified. For example, we fixed multiple Code Climate issues in the [https://github.com/gshugh/expertiza/commit/b9aac55b6eb331c1db295b7e7dd45fbbdba19abc app/models/team.rb] file. Specifically, complications of such issues as "Use a guard clause instead of wrapping the code inside a conditional expression", "Use ''find_by'' instead of ''where.first''", and others were resolved in ''import'', ''export'', and ''handle_duplicate'' method calls. Most of the changes are listed below:

[[File: app_models_teams_1.png]]
[[File: app_models_teams_2.png]]

Any of the above changes may break existing functionality of the code without proper testing. Moreover, we noticed that existing ''spec/models/team_spec.rb'' Rspec file does not thoroughly tests these method calls and had very a little to none of such tests. Hence, in order to verify and test all our changes, we wrote additional Rspec tests and added them into ''spec/models/team_spec.rb'' that specifically tests our code changes. ''Note'' that in the following test cases, we cover all possible scenarios, including edge-case scenarios. Check out [https://github.com/gshugh/expertiza/commit/96cec7fa82c1c55e31e0196d3a025111a4fe134a spec/models/team_spec.rb] for full list of Rspec tests. The following is a list of Rspec we developed to test all our changes in the ''app/models/team.rb'' file:

[[File: rspec_models_team_spec_1.png]]
[[File: rspec_models_team_spec_2.png]]
[[File: rspec_models_team_spec_3.png]]

''Note'' that this is only one small example we show here of additional Rspec tests we developed. Full list of newly developed and added Rspec tests can be found in our Git Pull Request. Also note that by adding new spec test cases, we increased test code coverage on all of the models. The test coverage for the ''app/models/team.rb'' model was increased up to 88.51% as follows:

[[File: spec_models_team_spec_test_coverage.png]]

=== New RSpec Testing ===

Moreover, while working with the existing Rspec tests, besides low coverage on some of the tests, we also noticed that some models are tested indirectly via other Rspec tests. Meaning there is no dedicated spec test file for some of the models that we fixed. Since we were not aware of what spec files are responsible for testing some models that have no dedicated spec test file, we did not know what are the exact set of test cases existing Rspec testing framework runs on these file (e.g. edge-case scenarios and etc). Similarly, as with existing Rspec tests we found out that existing specs would not suffice for the changes that we made. Therefore, we created '''new''' dedicated Rspec test files and wrote test cases that test our changes directly.

For example, we fixed multiple Code Climate issues in the ''app/models/teams_user.rb'' file. At the moment, there is no corresponding Rspec file for that model in the system. Therefore, we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to test directly our code changes and boost the code coverage on that model. The following is the change that we did in the ''app/models/teams_user.rb'' file:

[[File: app_models_teams_user_changes.png]]

The following is newly created corresponding ''spec/models/teams_test_spec.rb'' test file included in our Git Pull Request having all general-purpose tests in it as follows:

[[File: spec_models_teams_user_1.png]]
[[File: spec_models_teams_user_2.png]]
[[File: spec_models_teams_user_3.png]]

''Note'' that by creating new corresponding spec test for the ''app/models/teams_user.rb'' model, we achieved 100% test coverage on that model, whereas before it was around 60.53%.

[[File: spec_models_teams_user_test_coverage.png]]

Again this is only one example we show here of the files that we created. More additional spec files were created to test our code changes. For example, we made extensive changes by fixing "Tagging a string as html safe may be a security risk" Code Climate issue. Most of those models did not have corresponding Rspec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment. The test coverage on those models was also increased.

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

This represented 1440 lines of code and 68.19% of code coverage for the models of interest. The number of lines of code decreased by 4.64% (from 1510 to 1440), an increase in code coverage of 16.48% (from 58.54% to 68.19%) and an increase in test examples of 8.45% (from 817 to 886). The increase in the percentage of code coverage was due to a combination of the decrease in the number of lines and the increase in the number of test examples.

We also compared the test coverage before and after implementation of our project and there was increase of 1% on models with names starting with ''Se'' through ''Z''. To compare the results on the files that were fixed we ran the following command before and after our project implementation:

rspec spec/models/[se-z]*.rb

The following are results before our project implementation:

[[File: se_z_test_coverage_before.png]]

And the following are results after the project implementation:

[[File: se_z_test_coverage_after.png]]

Although 1% does not seem to be big improvements. However, this is 1% of the total code coverage and for such massive project 1% test coverage increase is significant!

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])! There are no more Code Climate issues found!

Although, in our project we were not asked to write additional Rspec tests, we dedicated some of our time to do so. The goal of writing additional spec test cases was to validate our code changes, make sure our changes did not cause any problems in the app, and boost the test coverage on the models we worked on. We achieved all our goals and tested all our changes with the help of Rspec tests that we wrote. We also ensured that our additional spec tests boost the code coverage.

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage on all of the existing files by writing more Rspec tests and considering more possible scenarios (i.e, edge-case scenarios).

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T20:55:27Z

Gshugh: /* New RSpec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.

Randomized with seed 29018
.........

Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending

Randomized with seed 29018

Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

We ran this command against master branch as a baseline, which produced the following results:

817 examples, 0 failure, 16 pending

These tests represented 1510 lines of code and 58.54% code coverage for our models.

However, while working with the existing RSpec tests, we noticed that some models have relatively low coverage (> 40%). Therefore, we could not rely strictly on existing RSpec tests and guarantee correctness of our code changes by running them. We decided to write additional Rspec tests that directly test all our code changes and add them into existing spec files by modifying existing tests and boost the test coverage on files that we modified. For example, we fixed multiple Code Climate issues in the [https://github.com/gshugh/expertiza/commit/b9aac55b6eb331c1db295b7e7dd45fbbdba19abc app/models/team.rb] file. Specifically, complications of such issues as "Use a guard clause instead of wrapping the code inside a conditional expression", "Use ''find_by'' instead of ''where.first''", and others were resolved in ''import'', ''export'', and ''handle_duplicate'' method calls. Most of the changes are listed below:

[[File: app_models_teams_1.png]]
[[File: app_models_teams_2.png]]

Any of the above changes may break existing functionality of the code without proper testing. Moreover, we noticed that existing ''spec/models/team_spec.rb'' Rspec file does not thoroughly tests these method calls and had very a little to none of such tests. Hence, in order to verify and test all our changes, we wrote additional Rspec tests and added them into ''spec/models/team_spec.rb'' that specifically tests our code changes. ''Note'' that in the following test cases, we cover all possible scenarios, including edge-case scenarios. Check out [https://github.com/gshugh/expertiza/commit/96cec7fa82c1c55e31e0196d3a025111a4fe134a spec/models/team_spec.rb] for full list of Rspec tests. The following is a list of Rspec we developed to test all our changes in the ''app/models/team.rb'' file:

[[File: rspec_models_team_spec_1.png]]
[[File: rspec_models_team_spec_2.png]]
[[File: rspec_models_team_spec_3.png]]

''Note'' that this is only one small example we show here of additional Rspec tests we developed. Full list of newly developed and added Rspec tests can be found in our Git Pull Request. Also note that by adding new spec test cases, we increased test code coverage on all of the models. The test coverage for the ''app/models/team.rb'' model was increased up to 88.51% as follows:

[[File: spec_models_team_spec_test_coverage.png]]

=== New RSpec Testing ===

Moreover, while working with the existing Rspec tests, besides low coverage on some of the tests, we also noticed that some models are tested indirectly via other Rspec tests. Meaning there is no dedicated spec test file for some of the models that we fixed. Since we were not aware of what spec files are responsible for testing some models that have no dedicated spec test file, we did not know what are the exact set of test cases existing Rspec testing framework runs on these file (e.g. edge-case scenarios and etc). Similarly, as with existing Rspec tests we found out that existing specs would not suffice for the changes that we made. Therefore, we created '''new''' dedicated Rspec test files and wrote test cases that test our changes directly.

For example, we fixed multiple Code Climate issues in the ''app/models/teams_user.rb'' file. At the moment, there is no corresponding Rspec file for that model in the system. Therefore, we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to test directly our code changes and boost the code coverage on that model. The following is the change that we did in the ''app/models/teams_user.rb'' file:

[[File: app_models_teams_user_changes.png]]

The following is newly created corresponding ''spec/models/teams_test_spec.rb'' test file included in our Git Pull Request having all general-purpose tests in it as follows:

[[File: spec_models_teams_user_1.png]]
[[File: spec_models_teams_user_2.png]]
[[File: spec_models_teams_user_3.png]]

''Note'' that by creating new corresponding spec test for the ''app/models/teams_user.rb'' model, we achieved 100% test coverage on that model, whereas before it was around 60.53%.

[[File: spec_models_teams_user_test_coverage.png]]

Again this is only one example we show here of the files that we created. More additional spec files were created to test our code changes. For example, we made extensive changes by fixing "Tagging a string as html safe may be a security risk" Code Climate issue. Most of those models did not have corresponding Rspec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment. The test coverage on those models was also increased.

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

This represented 1440 lines of code and 68.19% of code coverage for the models of interest. The number of lines of code decreased by 4.64% (from 1510 to 1440), an increase in code coverage of 16.48% (from 58.54% to 68.19%) and an increase in test examples of 8.45% (from 817 to 886). The increase in the percentage of code coverage was due to a combination of the decrease in the number of lines and the increase in the number of test examples.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])! There are no more Code Climate issues found!

Although, in our project we were not asked to write additional Rspec tests, we dedicated some of our time to do so. The goal of writing additional spec test cases was to validate our code changes, make sure our changes did not cause any problems in the app, and boost the test coverage on the models we worked on. We achieved all our goals and tested all our changes with the help of Rspec tests that we wrote. We also ensured that our additional spec tests boost the code coverage.

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage on all of the existing files by writing more Rspec tests and considering more possible scenarios (i.e, edge-case scenarios).

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T20:44:31Z

Gshugh: /* Existing Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.

Randomized with seed 29018
.........

Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending

Randomized with seed 29018

Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

We ran this command against master branch as a baseline, which produced the following results:

817 examples, 0 failure, 16 pending

These tests represented 1510 lines of code and 58.54% code coverage for our models.

However, while working with the existing RSpec tests, we noticed that some models have relatively low coverage (> 40%). Therefore, we could not rely strictly on existing RSpec tests and guarantee correctness of our code changes by running them. We decided to write additional Rspec tests that directly test all our code changes and add them into existing spec files by modifying existing tests and boost the test coverage on files that we modified. For example, we fixed multiple Code Climate issues in the [https://github.com/gshugh/expertiza/commit/b9aac55b6eb331c1db295b7e7dd45fbbdba19abc app/models/team.rb] file. Specifically, complications of such issues as "Use a guard clause instead of wrapping the code inside a conditional expression", "Use ''find_by'' instead of ''where.first''", and others were resolved in ''import'', ''export'', and ''handle_duplicate'' method calls. Most of the changes are listed below:

[[File: app_models_teams_1.png]]
[[File: app_models_teams_2.png]]

Any of the above changes may break existing functionality of the code without proper testing. Moreover, we noticed that existing ''spec/models/team_spec.rb'' Rspec file does not thoroughly tests these method calls and had very a little to none of such tests. Hence, in order to verify and test all our changes, we wrote additional Rspec tests and added them into ''spec/models/team_spec.rb'' that specifically tests our code changes. ''Note'' that in the following test cases, we cover all possible scenarios, including edge-case scenarios. Check out [https://github.com/gshugh/expertiza/commit/96cec7fa82c1c55e31e0196d3a025111a4fe134a spec/models/team_spec.rb] for full list of Rspec tests. The following is a list of Rspec we developed to test all our changes in the ''app/models/team.rb'' file:

[[File: rspec_models_team_spec_1.png]]
[[File: rspec_models_team_spec_2.png]]
[[File: rspec_models_team_spec_3.png]]

''Note'' that this is only one small example we show here of additional Rspec tests we developed. Full list of newly developed and added Rspec tests can be found in our Git Pull Request. Also note that by adding new spec test cases, we increased test code coverage on all of the models. The test coverage for the ''app/models/team.rb'' model was increased up to 88.51% as follows:

[[File: spec_models_team_spec_test_coverage.png]]

=== New RSpec Testing ===

Moreover, while working with the existing Rspec tests, besides low coverage on some of the tests, we also noticed that some models are tested indirectly via other Rspec tests. Meaning there is no dedicated spec test file for some of the models that we fixed. Since we were not aware of what spec files are responsible for testing some models that have no dedicated spec test file, we did not know what are the exact set of test cases existing Rspec testing framework runs on these file (e.g. edge-case scenarios and etc). Similarly, as with existing Rspec tests we found out that existing specs would not suffice for the changes that we made. Therefore, we created '''new''' dedicated Rspec test files and wrote test cases that test our changes directly.

For example, we fixed multiple Code Climate issues in the ''app/models/teams_user.rb'' file. At the moment, there is no corresponding Rspec file for that model in the system. Therefore, we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to test directly our code changes and boost the code coverage on that model. The following is the change that we did in the ''app/models/teams_user.rb'' file:

[[File: app_models_teams_user_changes.png]]

The following is newly created corresponding ''spec/models/teams_test_spec.rb'' test file included in our Git Pull Request having all general-purpose tests in it as follows:

[[File: spec_models_teams_user_1.png]]
[[File: spec_models_teams_user_2.png]]
[[File: spec_models_teams_user_3.png]]

''Note'' that by creating new corresponding spec test for the ''app/models/teams_user.rb'' model, we achieved 100% test coverage on that model, whereas before it was around 60.53%.

[[File: spec_models_teams_user_test_coverage.png]]

Again this is only one example we show here of the files that we created. More additional spec files were created to test our code changes. For example, we made extensive changes by fixing "Tagging a string as html safe may be a security risk" Code Climate issue. Most of those models did not have corresponding Rspec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment. The test coverage on those models was also increased.

After all of these changes to the Rspec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

The increase in the number of examples reflects the addition RSpec model tests that we wrote.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

Although, in our project we were not asked to write additional Rspec tests, we dedicated some of our time to do so. The goal of writing additional spec test cases was to validate our code changes, make sure our changes did not cause any problems in the app, and boost the test coverage on the models. We achieved all our goals and tested all our changes with the help of Rspec tests that we wrote.

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage on all of the existing files by writing more Rspec tests and considering more possible scenarios (i.e, edge-case scenarios).

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T00:30:19Z

Gshugh: /* Existing Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.

Randomized with seed 29018
.........

Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending

Randomized with seed 29018

Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
The master branch produced the following results:

871 examples, 0 failure, 16 pending

=== New RSpec Testing ===

While looking through the exisitng RSpec test, we noticed that some models are tested indirectly via other RSpec test. Since we did not know how intensively our changes are getting tested with the existing RSpec testing framework (e.g. edge-case scenarios and etc), and whether existing tests are enough, we wrote both '''new''' RSpec test cases and '''new''' RSpec test files.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we added new RSpect tests to test our code and to increase code coverage on certain files. For those, we ran the corresponding test via the terminal window as discussed above. For example, to test the tag_prompt model:
rspec spec/models/tag_prompt_spec.rb

Other models did not have any way to directly test our changes to the code. For example, we have made multiple changes in the ''app/models/teams_user.rb'' file. There is no corresponding RSpec file in the system so we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to directly our code changes. Another example, was the extensive changes we made to remove html_safe code. Most of those models did not have corresponding RSpec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment.

The change that we did in the ''app/models/teams_user.rb'' file as follows:
[[File: app_models_teams_user_changes.png]]

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

The increase in the number of examples reflects the addition RSpec model tests that we wrote.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T00:27:31Z

Gshugh: /* Existing Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 29018
.........
Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending
Randomized with seed 29018
Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
The master branch produced the following results:

871 examples, 0 failure, 16 pending

=== New RSpec Testing ===

While looking through the exisitng RSpec test, we noticed that some models are tested indirectly via other RSpec test. Since we did not know how intensively our changes are getting tested with the existing RSpec testing framework (e.g. edge-case scenarios and etc), and whether existing tests are enough, we wrote both '''new''' RSpec test cases and '''new''' RSpec test files.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we added new RSpect tests to test our code and to increase code coverage on certain files. For those, we ran the corresponding test via the terminal window as discussed above. For example, to test the tag_prompt model:
rspec spec/models/tag_prompt_spec.rb

Other models did not have any way to directly test our changes to the code. For example, we have made multiple changes in the ''app/models/teams_user.rb'' file. There is no corresponding RSpec file in the system so we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to directly our code changes. Another example, was the extensive changes we made to remove html_safe code. Most of those models did not have corresponding RSpec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment.

The change that we did in the ''app/models/teams_user.rb'' file as follows:
[[File: app_models_teams_user_changes.png]]

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

The increase in the number of examples reflects the addition RSpec model tests that we wrote.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T00:27:03Z

Gshugh: /* Existing Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we ran the corresponding test via the terminal window. For example, to test the simi_check_webservice model:
rspec spec/models/simi_check_webservie_spec.rb

This executes the RSpec test for the simi_check_webservice model, app/models/simi_check_webervice.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/simi_check_webservice_spec.rb
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.

Randomized with seed 29018
.........

Finished in 1.63 seconds (files took 28.35 seconds to load)
10 examples, 0 failures, 10 pending

Randomized with seed 29018

Coverage report generated for RSpec to /home/expertiza_developer/expertiza/coverage. 1192 / 17393 LOC (6.85%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
The master branch produced the following results:

871 examples, 0 failure, 16 pending

=== New RSpec Testing ===

While looking through the exisitng RSpec test, we noticed that some models are tested indirectly via other RSpec test. Since we did not know how intensively our changes are getting tested with the existing RSpec testing framework (e.g. edge-case scenarios and etc), and whether existing tests are enough, we wrote both '''new''' RSpec test cases and '''new''' RSpec test files.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we added new RSpect tests to test our code and to increase code coverage on certain files. For those, we ran the corresponding test via the terminal window as discussed above. For example, to test the tag_prompt model:
rspec spec/models/tag_prompt_spec.rb

Other models did not have any way to directly test our changes to the code. For example, we have made multiple changes in the ''app/models/teams_user.rb'' file. There is no corresponding RSpec file in the system so we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to directly our code changes. Another example, was the extensive changes we made to remove html_safe code. Most of those models did not have corresponding RSpec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment.

The change that we did in the ''app/models/teams_user.rb'' file as follows:
[[File: app_models_teams_user_changes.png]]

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

The increase in the number of examples reflects the addition RSpec model tests that we wrote.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-04-01T00:18:04Z

Gshugh: /* Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed four simple test steps:
# Code inspection
# Passing/fixing existing RSpec tests
# '''Developing new RSpec tests'''
# Running through a live demo in the Expertiza instance through the UI
''Note'' that per project's requirement specifications we were not required to develop and write newly RSpec tests. However, ultimately we strive to achieve crucial improvements over code quality, robustness, and maintainability for the files that we have worked on. We believe we achieved our goal. We did not do this to gain extra credit or something similar. We did it because we believe in testing and convinced that nothing can improve Expertiza source code like testing.

There are 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Existing Rspec Testing ===

To verify that the code changes we made did not break the existing application and its functionalities, we used the RSpec Testing Framework to test all the code.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we added new RSpect tests to test our code and to increase code coverage on certain files. For those, we ran the corresponding test via the terminal window. For example, to test the tag_prompt model:
rspec spec/models/tag_prompt_spec.rb

This executes the RSpec test for the tag_prompt model, app/models/tag_prompt.rb. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results are displayed:
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
The master branch produced the following results:

871 examples, 0 failure, 16 pending

=== New RSpec Testing ===

While looking through the exisitng RSpec test, we noticed that some models are tested indirectly via other RSpec test. Since we did not know how intensively our changes are getting tested with the existing RSpec testing framework (e.g. edge-case scenarios and etc), and whether existing tests are enough, we wrote both '''new''' RSpec test cases and '''new''' RSpec test files.

Some of the models already had existing RSpecs tests created prior we started on work on the project. For those models, we added new RSpect tests to test our code and to increase code coverage on certain files. For those, we ran the corresponding test via the terminal window as discussed above. For example, to test the tag_prompt model:
rspec spec/models/tag_prompt_spec.rb

Other models did not have any way to directly test our changes to the code. For example, we have made multiple changes in the ''app/models/teams_user.rb'' file. There is no corresponding RSpec file in the system so we created a new [https://github.com/gshugh/expertiza/blob/beta/spec/models/teams_user_spec.rb spec/models/teams_user_spec.rb] file to directly our code changes. Another example, was the extensive changes we made to remove html_safe code. Most of those models did not have corresponding RSpec files, so we added those RSpec files to allow developers to have some confidence in the code before deployment.

The change that we did in the ''app/models/teams_user.rb'' file as follows:
[[File: app_models_teams_user_changes.png]]

After all of these changes to the RSpec files, our beta branch produced the following results:

886 examples, 0 failure, 16 pending

The increase in the number of examples reflects the addition RSpec model tests that we wrote.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-28T18:44:19Z

Gshugh: /* Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify that the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
In both cases, the command produced the following results:

871 examples, 0 failure, 16 pending

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-28T18:43:42Z

Gshugh: /* UI Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
In both cases, the command produced the following results:

871 examples, 0 failure, 16 pending

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped to reveal all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-28T18:42:51Z

Gshugh: /* Rspec Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec tests, we also ensured that all previous RSpec tests passed. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec spec/controllers spec/models

This command was run against the master branch as a baseline and our beta branch.
In both cases, the command produced the following results:

871 examples, 0 failure, 16 pending

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-27T23:55:39Z

Gshugh: /* Remaining Issues */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)
# simicheck_webservice.rb (1)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-27T14:42:09Z

Gshugh: /* Remaining Issues */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-27T14:41:03Z

Gshugh: /* Remaining Issues */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

There is also an issue with methods that were commented out in the original code. While the team removed code that we changed, we also made a conscious decision to leave existing commented out methods in the code and let the original maintainer decide if the comment should be removed. The following files had existing commented out methods:
# sign_up_topic (2)

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-27T14:25:39Z

Gshugh: /* Additional Improvements */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-27T14:22:40Z

Gshugh: /* UI Testing */

This wiki page describes the changes are made in the Expertiza source code to implement OSS Project "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''" for the CSC/ECE 517: "Object-Oriented Design and Development", Spring semester of the 2019.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS Project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned to [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920 - Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] OSS Project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where is needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===
We created a [https://github.com/expertiza/expertiza/pull/1368 Pull Request] as soon as we had at least one fix on our [https://github.com/gshugh/expertiza/tree/beta forked beta branch].

GitHub pull request is an integral part of solving Code Climate issues and delivering fixes into the Expertiza beta branch. We verified all our Code Climate fixes on the local working repositories, which we registered with Code Climate tool. Every new git commit/push was triggering new Code Climate job and we could verify if our changes fixed the issues. A typical workflow was as follows:
* Code Climate issues were resolved and tested locally
* Changes were pushed to local repositories registered with Code Climate
* New git commit/push was triggering new Code Climate verification job
* Verified that resolved issues were not reported on the latest Code Climate job
All our changes are visible and can be tracked in the single pull requests we created as soon as we had one fix.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# Pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-26T01:59:47Z

Gshugh: /* UI Testing */

This wiki page describes the changes are made in the Expertiza source code to implement E1920 OSS Project, "Fix Code Climate issues in models with names beginning with 'Se' thru 'Z'" in the Spring 2019 semester, CSC/ECE 517.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned with [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920. Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] Expertiza project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where is needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===

GitHub pull requests were an integral part of solving Code Climate issues. We found that in order for Code Climate to re-analyze new code, it had to be via pull requests. A typical workflow was as follows:
- Code Climate issues were tested in RubyMine and pushed to testing repositories
- A pull request was created against the beta repository
- The pull request triggered an analysis by Code Climate
- A refresh of the code page on GitHub allowed us to see which Code Climate issues were fixed and which ones were still open.
- After all relevant Code Climate issues were fixed, the changes were pushed to the beta branch of the GitHub repository, which also closed the pull request.
- The next file was opened in RubyMine and we started at the beginning.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on four types of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
# pages that previously used html_safe
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-26T01:55:55Z

Gshugh: /* Pull Request */

This wiki page describes the changes are made in the Expertiza source code to implement E1920 OSS Project, "Fix Code Climate issues in models with names beginning with 'Se' thru 'Z'" in the Spring 2019 semester, CSC/ECE 517.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned with [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920. Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] Expertiza project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where is needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===

GitHub pull requests were an integral part of solving Code Climate issues. We found that in order for Code Climate to re-analyze new code, it had to be via pull requests. A typical workflow was as follows:
- Code Climate issues were tested in RubyMine and pushed to testing repositories
- A pull request was created against the beta repository
- The pull request triggered an analysis by Code Climate
- A refresh of the code page on GitHub allowed us to see which Code Climate issues were fixed and which ones were still open.
- After all relevant Code Climate issues were fixed, the changes were pushed to the beta branch of the GitHub repository, which also closed the pull request.
- The next file was opened in RubyMine and we started at the beginning.

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on three type of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-26T01:48:04Z

Gshugh: /* Most Common Issues Reported by Code Climate */

This wiki page describes the changes are made in the Expertiza source code to implement E1920 OSS Project, "Fix Code Climate issues in models with names beginning with 'Se' thru 'Z'" in the Spring 2019 semester, CSC/ECE 517.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned with [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920. Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] Expertiza project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false)
We did find that there was some HTML code that was not properly rendered using the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text in HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to allow them to properly render. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where is needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===

Let's add some info about pull request

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on three type of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-26T01:45:13Z

Gshugh: Add html_safe fixes.

This wiki page describes the changes are made in the Expertiza source code to implement E1920 OSS Project, "Fix Code Climate issues in models with names beginning with 'Se' thru 'Z'" in the Spring 2019 semester, CSC/ECE 517.

== Introduction ==

This Wiki page is created per CSC/ECE 517: "Object-Oriented Design and Development", OSS project 3 requirements (Spring, 2019).

Our [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Team_Contacts_and_Contribution team] was assigned with [https://docs.google.com/document/d/17tkcuA7AWgGEzDGpjEJ7ktPzbSr-D89MJZd-cXzSCuE/edit#heading=h.jes8j9o3codt "E1920. Fix Code Climate issues in models with names beginning with ''Se'' thru ''Z''"] Expertiza project. In this page we describe what work has been completed by our team to improve overall quality, readability, maintainability and efficiency of the Expertiza source code. What approaches we used to resolve issues reported by Code Climate, what are the remaining issues in the Expertiza code, our suggestions for further improvements and our testing strategy used to ensure integrity of the code. Each section below provides clear and descriptive review on the subject we cover.

We start with introduction to Expertiza application and Code Climate tool. How Code Climate is used to improve Expertiza source code.
=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify shortcomings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of software. The Code Climate generated results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate utilizes various engines to analyze the code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can be ran from either a 3-rd party remote server of via the local application using CLI. The Expertiza project uses the 3-rd party remote server to analyze the code. In order to use Code Climate via remote server, desired repository must be registered with Code Climate. Following [https://docs.codeclimate.com/docs this] process allows to test the code for quality issues after each git commit/push to a registered repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness, efficiency, and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files. In this section we specify what files we have changed to improve overall software of the Expertiza project. We also list and describe the issues that we were asked to ignore during implementation of our project.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

In this section we talk about implementation of our project. We start with the most common issues reported by Code Climate and what approach we used to resolve them. We provide some code samples taken from the files and show their improvements. These changes/improvements are not trivial and require understanding of the code. Therefore, we provide implementation details of such issues along with detailed explanations.

Furthermore, we list all of the issues reported by Code Climate that we fixed. These changes/improvements are trivial and require no explanation. Therefore, any implementation details are excluded for these type of issues.

Next, we cover section with additional improvements that we have done along with fixes for Code Climate issues. These improvements do not directly relate to Code Climate issues; however, they improve overall quality of the code, its readability, maintenance and efficiency.

We also list and talk about remaining issues reported by Code Climate that were intentionally ignored and left in the project. We provide further suggestions based on our experience to the Expertiza software developers.

Finally, we provide out pull request that our team created as we started to work on this project.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue warns the user that strings tagged with html_safe can leave your site vulnerable to XSS attacks. To overcome this issue, we chose to use content_tag and tag helpers to create HTML tags. By using this practice we are able to create HTML strings that are actually HTML safe and we minimize the possibility of XSS attacks. A common use is:
# Bad - uses html_safe
html = '<b style="color: #986633;">' + self.txt + '</b>'.html_safe

# Good - use content_tag
html = content_tag(:b, self.txt, {style: "color: #986633"}, false
We did find that there were some HTML code that could not fit into the content_tag paradigm. This HTML code involved user supplied answers. These answers were created using a rich text editor called TinyMCE. TinyMCE wraps parts of the text with HTML tags and our mentor warned us against trying to decode these strings. For these strings we used the raw() function to include them in the HTML string. For example,
concat self.txt + raw(answer.comments)
This use of raw() is in two files, text_field.rb and text_area.rb. If a better solution is found, please let the authors know.
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where is needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===

Let's add some info about pull request

== Testing ==
To test integrity of the code and ensure that our changes/improvements did not introduce new issues/errors, we followed three simple test steps:
# Code inspection
# Passing/fixing existing Rspec tests
# Running through a live demo in the Expertiza instance through the UI
''Note'' that we did not write new Rspec tests since we were not explicitly asked to do so in the project requirements.

There we 2 types of frameworks that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI analyzes the code once the changes are Pushed to the GitHub server for desired repository. Travis CI needs to be setup independently for desired repository.
=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on three type of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Code Climate is a powerful tool that finds flaws in the source code of the Expertiza project. We would like to acknowledge that all issues reported by Code Climate on the files beginning with ''Se'' thru ''Z'' under ''app/models'' directory were fixed (except [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells])!

We encourage software developers working on the Expertiza project to maintain clean, readable, well-commented and efficient code. We suggest to achieve at least 85% of test coverage by writing more Rspec tests.

We would like to thank our mentor (Zachariah Mathews) and teaching staff for all the assistance and help they provided to us during the project implementation.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]

E1920 Fix Code Climate Issues

2019-03-25T22:15:55Z

Gshugh: /* Most Common Issues Reported by Code Climate */

This wiki page describes the changes are made in the Expertiza source code to implement E1920 OSS Project, "Fix Code Climate issues in models with names beginning with 'Se' thru 'Z'" in the Spring 2019 semester, CSC/ECE 517.

== Introduction ==

This is intro section. We can talk about what is our project and how we got started.

=== Expertiza ===

[https://expertiza.ncsu.edu/ Expertiza] is a peer to peer application whereby students gain knowledge through submitting their work into the system and review the work of others. This is system diverges from the customary systems where a instructor or body of teaching staff would grade the papers/assignments and provide feedback to the students. This process misses out on a learning opportunity for students performing reviews. Allowing students to see the work of others allows them to see more code examples and from different aspects. This exercise during the review process forces the student to think through lecture material and apply during the process. The Expertiza application can also be used as an iterative process from class to class. The examples of the current semester can be used by students of subsequent semesters to identify short comings and suggest further improvements.

=== Code Climate ===

Code Climate is an analysis software used to improve the quality and security of your code. The Code Climate results for the Expertiza project can be found [https://codeclimate.com/github/expertiza/expertiza/code here].

Code Climate will use various engines to analyze your code to look for issues that may concern potential security issues, (.i.e. marking code to html_safe), or add to maintainability issues (.i.e number of lines in method exceeding 25 lines). Some of the engines include: RuboCop, Brakeman, Bundler-Audit, [https://docs.codeclimate.com/docs/list-of-engines etc.]

Code Climate can ran from either a 3rd party remote server of via the local application using CLI. The Expertiza project uses the 3rd party remote server to analyze the code. In order to use CodeClimate via remote server, you have to register your repository. Following [https://docs.codeclimate.com/docs this] process will allow you to check your code for quality issues after Pushing your code to the monitored repository.

== Project Description ==

Some of the Expertiza source code violates many of the [https://rubyonrails.org/ Ruby on Rails] best practices and must be rectified to improve code readability, robustness and maintainability of the Expertiza application.

Our team was assigned to fix ''all'' code smells detected by [https://codeclimate.com/github/expertiza/expertiza/code Code Climate] in the given set of Expertiza source code files.

=== Files Involved ===

All files in the [https://github.com/expertiza/expertiza/tree/master/app/models app/models] directory with names beginning with '''Se''' (e.g. [https://github.com/expertiza/expertiza/blob/master/app/models/section_header.rb section_header.rb]) through '''Z''', except [https://github.com/expertiza/expertiza/blob/master/app/controllers/users_controller.rb users_controller.rb] file were targeted by our team to be Code Climate issue free files. Therefore, our team was assigned exactly with 50 (fifty) files to fix in total. Some of the files had no issues reported by the Code Climate to begin with, and hence were not modified. However, changes/improvements performed on other files had an affect globally on the files outside of the app/models scope and also had to be modified to adapt changes we implemented. For example, renaming method ''is_leaf'' as follows:
def leaf?
in the [https://github.com/expertiza/expertiza/blob/master/app/models/team_user_node.rb team_user_node.rb] file require to change all callers to this method in different files accordingly. Such changes had to be done in the following files (for this particular example):
<ul>
<li> models/assignment_node.rb
<li> models/node.rb
<li> models/questionnaire_node.rb
<li> views/tree_display/_row_header.html.erb
</ul>

These files are outside of the requirements specifications, but we had to modify them in order to maintain correct behavior of the App. There were few such cases when we had to modify multiple files to fix one or more Code Climate issue(s). The list of all of files changed can be found in the Pull Request discussed in this article.

=== Ignored Code Climate Smells ===

There are some Code Climate issues that were ignored and not resolved intentionally.

The following issues are exempt based the given requirements specifications and were not fixed:
<ul>
<li> Assignment Branch Condition size for [method name] is too high.
<li> Perceived complexity for [method name] is too high.
<li> Cyclomatic complexity for [method name] is too high.
<li> Method [method name] has a Cognitive Complexity of ''XX'' (exceeds 5 allowed). Consider refactoring.
<li> File [file name] has ''XXX'' lines of code (exceeds 250 allowed). Consider refactoring.
<li> Class [class name] has ''XX'' methods (exceeds 20 allowed). Consider refactoring.
<li> Method [method name] has ''XX'' lines of code (exceeds 25 allowed). Consider refactoring.
</ul>

There are also two Code Climate issues that our team decided to ignore after consulting our mentor and discussing their impact on the existing code and Expertiza project. It was determined that the following Code Climate issues reported as False Positive and may not need to be resolved:
<ul>
<li> Mass assignment is not restricted using attr_accessible.
<li> Potentially dangerous attribute available for mass assignment.
</ul>

Finally, there was a duplicate code issue that was ignored due to a future project. The following files have a duplicate method, self.export_fields(options):
<ul>
<li> user.rb
<li> participant.rb
</ul>

For further clarification with regard to ignored Code Climate issues please contact our mentor.

== Project Implementation ==

Talk about how we fixed the most common issues reported by Code Climate.

=== Most Common Issues Reported by Code Climate ===

As we worked on the Code Climate issues for the Expertiza project, we noticed a set of common code smells and issues made by software developers. Since these issues can easily be avoided and most importantly, avoiding them improves code quality, we decided to ''warn'' all Expertiza developers about them by providing the list of these issues, their descriptions, how they can be avoided, and how the code quality can be improved.

* Do not use ''Time.now'' or ''Time.parse'' without zone.
This is very common issue reported by Code Climate. Since time is relative and may have different values (UTC, EST, and etc), it is a good practice to specify the time zone, whenever the ''Time'' class used.

'''Note''' that ''Time.parse'' and ''Time.zone.parse'' behave differently for invalid or unknown time. While returns an error for invalid or unknown times, returns nil for those types.
<ul>
<ul>
<li> ''Time.parse'' - returns an error for invalid or unknown time. Generally, can be handled by ''rescue''
<li> ''Time.zone.parse'' - returns ''nil'' for invalid or unknown time. It must be handled differently.
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if invalid or unknown time is given (with ''if/else'' block, ''return'', or ''or'' statements, and etc.) Do not assume that time will always be valid instance. For example, (code sample is used from ''app/models/student_task.rb'' file):
# Bad - use Time without zone and rescue if time is invalid or unknown
stage_deadline: (Time.parse(participant.stage_deadline) rescue Time.now + 1.year)

# Good - use Time with zone and using or statement to handle nil case
stage_deadline: (Time.zone.parse(participant.stage_deadline) || (Time.zone.now + 1.year))
Above example is good practice how ''Time'' class should be used.
* Method ''x'' has ''n'' arguments (exceeds 4 allowed). Consider refactoring:
Any method that takes more than 4 arguments must be refactored with accordance to good RoR coding standards. There are multiple ways to refactor signature of such methods and there is no single standard way of resolving this issue. Each method must be considered separately and requires unique approach to refactor, utilizing hash, array and other Ruby's built-in libraries and tools. Below we provide one sample of how fixed such issue utilizing Ruby's built-in hash (code sample is used from ''app/models/vm_question_response_row.rb'' file):
# Bad - initialize method has 5 arguments
def initialize(question_text, question_id, weight, question_max_score, seq)
@question_text = question_text
@weight = weight
@question_id = question_id
@question_seq = seq
@question_max_score = question_max_score

# Good - initialize method has 1 argument, hash
def initialize(question_data)
@question_text = question_data[:text]
@question_id = question_data[:id]
@weight = question_data[:weight]
@question_max_score = question_data[:max_score]
@question_seq = question_data[:seq]
''Note'' that since method signature is changed, it of the callers must be changed accordingly to adapt new method signature. For example, the following is illustration of such change to adapt above refactored method signature (code sample is used from ''app/models/vm_question_response.rb'' file):
# Bad - passing in 5 arguments to the constructor
row = VmQuestionResponseRow.new(question.txt, question.id, question.weight, question_max_score, question.seq)

# Good - passing in 1 argument to the constructor, hash
row = VmQuestionResponseRow.new(text: question.txt, id: question.id, weight: question.weight, max_score: question_max_score, seq: question.seq)
* Prefer ''each'' over ''for'':
We noticed there is a lot of iteration in the code using ''for'' loop instead of ''each''. Generally, you want to avoid any ''for'' loops and use ''each'', ''each_index'', ''each_with_index'', ''upto'' and etc. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for user_signup_topic in user_signup
return false if user_signup_topic.is_waitlisted == false

# Good - use of each
user_signup.each do |user_signup_topic|
return false if user_signup_topic.is_waitlisted == false
Similarly, if you need to iterate the given block, passing in integer as an index, utilize ''each_index'', ''each_with_index'', ''upto'' instead of ''for''. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' file):
# Bad - use of for loop
for round in 1..@review_rounds
process_review_round(assignment_id, due_date, round, topic)

# Good - use of upto
1.upto(@review_rounds) do |r|
process_review_round(assignment_id, due_date, r, topic)
* Specify an '':inverse_of option'':
Whenever there are two models defined with many|one-to-one relationship (''has_many''|''has_one'' and ''belongs_to'' association) out of scope of each other or with certain options used (e.g. ''foreign_key:'' and etc.), Active Record is unable to determine the inverse association of them. This would cause redundant look up operation performed on the database for the same object. It is not really an issue that could cause significant problems, but for such massive application like Experiza, it could affect performance and cause delay in response. Therefore, the '':inverse_of'' option must be specified manually to use the associated object in memory instead of loading it from database twice. For example, (code sample is used from ''app/models/teams_user.rb'' and ''app/models/team_user_node.rb'' files respectively):
class TeamsUser < ActiveRecord::Base
has_one :team_user_node, foreign_key: 'node_object_id', dependent: :destroy, inverse_of: 'node_object'
end

class TeamUserNode < Node
belongs_to :node_object, class_name: 'TeamsUser', inverse_of: :team_user_node
end
* Specify a '':dependent'' option:
The [https://guides.rubyonrails.org/association_basics.html#the-has-many-association has_many] association should always be specified with one of the [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options :dependent] options, which specifies the behavior of the associated objects whenever their owner is destroyed. This is common practice and should be utilized adequately for the Expertiza app to work correctly. No specifying '':dependent'' option could lead to run time errors, unpredictable behavior of the app, and creating orphan objects that will never be referenced again. Specify a '':dependent'' option whenever utilizing ''has_many'' association. For example, (code sample is used from ''app/models/site_controller.rb'' file):
# Bad - not specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions

# Good - specifying a :dependent option
class SiteController < ActiveRecord::Base
has_many :controller_actions, dependent: :destroy
* Tagging a string as html safe may be a security risk. This Code Climate issue
For example,
html.html_safe # George can you please talk about it how you fixed it
* Use a guard clause instead of wrapping the code inside a conditional expression.
This is very common issue reported by Code Climate that can be easily avoided by properly utilizing `if` statements applying some logic. In general, avoid using bulk of ''if/else'' statements whenever possible. For example, (code sample is used from ''app/models/sign_up_topic.rb'' file):
# Bad - too many conditional expressions that also contain nested ones
if !no_of_students_who_selected_the_topic.nil?
if topic.max_choosers > no_of_students_who_selected_the_topic.size
return true
else
return false
end
else
return true
end

# Good - use guard close
return true if no_of_students_who_selected_the_topic.nil?
topic.max_choosers > no_of_students_who_selected_the_topic.size
Above is typical example when 9 lines of code (LoC) can be reduced to 2 LoC and overall code quality improved.
* Use ''find_by'' instead of ''where.first'':
Always use ''find_by'' with an attempt to find the first record matching the specified conditions.

'''Note''' that ''find_by'' and ''where.first'' behave differently if no record was found based on specified conditions.
<ul>
<ul>
<li> ''Model.find_by'' - if there is a record match, returns the object. If there is no record match, returns ''nil''
<li> ''Model.where.first'' - if there is a record match, returns first ActiveRecord::Relation matched. If there is no record match, returns an ''empty'' ActiveRecord::Relation
</ul>
</ul>
Therefore, always handle ''nil'' appropriately if there is no record match (with ''if/else'' block, ''return'' statement and etc.) Do not assume that the record will always be found (since ''empty'' relation skips iteration and ''nil'' throws an error if attempt to iterate). For example,
user = User.find_by(name: row_hash[index.to_sym].to_s)
raise ImportError, "The user, " + row_hash[index.to_sym].to_s.strip + ", was not found." if user.nil?
Similar to this issue Code Climate reported "Use ''find_by'' instead of dynamic ''find_by_name''" issue. It is resolved in the same manner as the above issue by changing ''find_by_name'' to ''find_by'' query and properly handling returned edge-cases (e.g. ''nil'').
* Use ''snake_case'' for method names and for variable names:
There are a lot of instances where developers use ''camelCase'' instead of ''snake_case'' in the Expertiza project naming methods and variables. Since Expertiza project is based on RoR, it is preferred to use ''snake_case'' for all method and variable names. For example, (code sample is used from ''app/models/sign_up_sheet.rb'' and ''app/models/sign_up_topic.rb'' files receptively):
# Bad method name - camelCase
def self.slotAvailable?(topic_id)

# Good method name - snake_case
def self.slot_available?(topic_id)

# Bad variable name - camelCase
dropDate = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

# Good method name - snake_case
drop_date = AssignmentDueDate.where(parent_id: assignment.id, deadline_type_id: '6').first

=== Resolved Code Climate Issues ===

Along with [http://wiki.expertiza.ncsu.edu/index.php/E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] we also fixed and verified numerous other code smells. The following is the list of all issues we have resolved. We do not provide solutions for them since most of them were trivial code changes.

<ul>
<li> Argument ''x'' was shadowed by a local variable before it was used.
<li> Avoid more than 3 levels of block nesting.
<li> Avoid too many return statements within the method.
<li> Avoid using ''update_attribute'' because it skips validations.
<li> Combine ''_type" type="text">'' and " into a single string literal, rather than using implicit string concatenation.
<li> Consider simplifying this complex logical expression.
<li> Convert ''if'' nested inside ''else'' to ''elsif''.
<li> Do not introduce global variables.
<li> Do not place comments on the same line as the ''end'' keyword.
<li> Do not prefix reader method names with ''get_''.
<li> Do not prefix writer method names with ''set_''.
<li> Do not use ''DateTime.parse.strftime'' without zone. Use one of ''Time.zone.parse.strftime'', ''DateTime.current'', ''DateTime.parse.strftime.in_time_zone'', ''DateTime.parse.strftime.utc'', ''DateTime.parse.strftime.getlocal'', ''DateTime.parse.strftime.iso8601'', ''DateTime.parse.strftime.jisx0301'', ''DateTime.parse.strftime.rfc3339'', ''DateTime.parse.strftime.to_i'', ''DateTime.parse.strftime.to_f'' instead.
<li> Extra empty line detected at method body beginning.
<li> Extra empty line detected at method body end.
<li> ''end'' at ''xxx'', ''xx'' is not aligned with ''unless'' (or ''def'') at ''xxx'', ''xx''.
<li> Identical blocks of code found in ''n'' locations. Consider refactoring.
<li> Line is too long.
<li> Method ''x'' is defined at both ''app/models/y.rb'' and ''app/models/z.rb''
<li> Optional arguments should appear at the end of the argument list.
<li> Place the condition on the same line as ''elsif''.
<li> Prefer Date or Time over DateTime.
<li> Redundant use of ''Object#to_s'' in interpolation.
<li> Rename ''has_x'' to ''x?''.
<li> Rename ''is_x'' to ''x?''.
<li> Replace class var ''@@variable_name'' with a class instance var.
<li> Similar blocks of code found in ''n'' locations. Consider refactoring.
<li> Unnecessary spacing detected.
<li> Unused method argument - ''x''. If it's necessary, use ''_'' or ''_x'' as an argument name to indicate that it won't be used.
<li> Use ''find_by'' instead of ''where.first''.
<li> Use ''x.zero?'' instead of ''x == 0''.
<li> Use ''=='' if you meant to do a comparison or wrap the expression in parentheses to indicate you meant to assign in a condition.
<li> Useless assignment to variable - ''x''.
<li> Variable ''x'' used in void context.
</ul>

=== Additional Improvements ===

While our primary task was to fix code smells reported by Code Climate, we also attempted to improve overall quality of code along the way. We introduced several minor changes that we believe improve the code, and encourage all software engineers working on the Expertiza source code to maintain clean and efficient software. All additional improvements are listed and described below.

* Meaningful names for class and instance variables.
There were several files where names for class or instance variables did not meet good naming conventions. For example, in the ''app/models/vm_question_response_row.rb'' file, instance variable
no_of_columns
indicating number of columns that refer to count of reviews, was re-named with
count_columns
Above is only an example of how we attempted to improve readability of the code.
* More comments where is needed.
In general there is sufficient amount of comments to fully understand the code and follow the flow. However, some of the functionalities are not as trivial and additional comments help a lot faster understand what the code does.
We added such comments in all the places where we fixed Climate Code issues. We also ensured to provide only sufficient comments to keep code as clean as possible and at the same time to clarify any complexity.
* Eliminate DRY code.
We tried to combine all of the duplicated code into a single functionality and eliminate any repetitive statements. Most of these issues were taken care by fixing "Similar blocks of code found in ''n'' locations" and "Identical blocks of code found in ''n'' locations" Code Climate issues. However, in some files Code Climate did not report such issues, although there were obvious repetitive statements. For example, ''add_reviews'' method in the ''app/models/vm_question_response.rb'' file had 4 places of the repetitive code and it was different only by data retrieved from various tables as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
reviews.each do |review|
review_mapping = ReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "AuthorFeedbackQuestionnaire"
reviews = participant.feedback
reviews.each do |review|
review_mapping = FeedbackResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "TeammateReviewQuestionnaire"
reviews = participant.teammate_reviews
reviews.each do |review|
review_mapping = TeammateReviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
elsif @questionnaire_type == "MetareviewQuestionnaire"
reviews = participant.metareviews
reviews.each do |review|
review_mapping = MetareviewResponseMap.find_by(id: review.map_id)
# Repetitive code as everywhere else
The above duplicate code was refactored to eliminate all repetitive statements and make the code more efficient as follows:
if @questionnaire_type == 'ReviewQuestionnaire'
reviews = ...
response_map = 'ReviewResponseMap'.constantize
elsif @questionnaire_type == 'AuthorFeedbackQuestionnaire'
reviews = participant.feedback
response_map = 'FeedbackResponseMap'.constantize
elsif @questionnaire_type == 'TeammateReviewQuestionnaire'
reviews = participant.teammate_reviews
response_map = 'TeammateReviewResponseMap'.constantize
elsif @questionnaire_type == 'MetareviewQuestionnaire'
reviews = participant.metareviews
response_map = 'MetareviewResponseMap'.constantize
end
# All repetitive code was extracted and now is common
unless reviews.nil?
reviews.each do |review|
review_mapping = response_map.find_by(id: review.map_id)
# Repetitive code
Again this is only single sample where improvements was made.

=== Remaining Issues ===

Unfortunately, Expertiza has some remaining issues reported by Code Climate in the files under ''app/models'' directory (names beginning with '''Se''' through '''Z''') that we were asked to ignore in this project. These issues described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Ignored_Code_Climate_Smells Ignored Code Climate Smells] section above and why there were ignored. Although these code smells do not impose any problems into existing code and application, we strongly believe that all of remaining issues must be fixed.

We did not find any further issues besides what we already reported and fixed it.

=== Further Suggestions ===

We suggest and encourage to fix all of the remaining issues that were intentionally ignored per the projects requirements in all of the files under ''app/models'' directory.

We also suggest to maintain clean, efficient, well-commented, and well-tested code in the Expertiza project. Prior delivering any changes to the ''master'' or ''beta'' branches, we recommend to test your software in the following manner:
# Code inspection
# Passing existing Rspec tests
# Adding new Rspec test that cover changes
# Running through a live demo in the Expertiza instance through the UI
Furthermore, we noticed that currently Expertiza project has ~53% test coverage, which is relatively small test coverage for such a massive project. Remember, "Debugging - sucks, and Testing - rocks!". We encourage Expertiza software developers to reach at least (minimum) 85% test coverage. That must cover all vital functionalities of the application and reduce any possibilities of introducing new issues into the system.

=== Pull Request ===

Let's add some info about pull request

== Testing ==
There we 2 types of frame works that we used to verify our code modifications/creation within the models: RSpec and Travis CI.

RSpec was used to locally test the changes we had implemented without having to Push the change to the GitHub, this is discussed more in-depth in the section below.

Travis CI is a more comprehensive testing used by the Expetiza team to verify code changes from multiple sources, (.i.e forks from students). Travis CI will analyze the code once you Push your changes to the GitHub server for your given repository. Travis CI will need to be setup independently for your repository

Talk about Testing we performed

=== Rspec Testing ===

To verify the code changes we made did not break the existing application, we used the RSpec Testing Framework. Several of the models already had existing RSpecs Tests already created. For those, we just simply ran the corresponding test via the terminal window. Example
rspec spec/models/tag_prompt_spec.rb

*rspec path/to/spec/file.rb*

This would execute the RSpec test for the tag_prompt.rb file located in the app/models folder. As you can see, there is a particular format that is used when naming the RSpec file:
model_name_spec.rb

Once the execution of the RSpec model testing is completed, results will be display
$ rspec spec/models/tag_prompt_spec.rb [10:45:15]
[Coveralls] Set up the SimpleCov formatter.
[Coveralls] Using SimpleCov's 'rails' settings.
Randomized with seed 19443
.........
Finished in 3.35 seconds (files took 23.23 seconds to load)
9 examples, 0 failures
Randomized with seed 19443
Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 1254 / 17313 LOC (7.24%) covered.
[Coveralls] Outside the CI environment, not sending data.

In addition to running the individual RSpec Test, we also executed broader in scope testing. To achieve this, we executed the following command in the terminal window:
$ bundle exec rspec --seed 5114

This produces the following results:

Finished in 1 minute 11.23 seconds (files took 23.19 seconds to load)
131 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/features/assignment_creation_spec.rb:707 # assignment function check to find if the assignment can be added to a course

Randomized with seed 5114

Coverage report generated for RSpec to /home/expertiza_developer/RubymineProjects/expertiza_testbed/coverage. 2998 / 14031 LOC (21.37%) covered.
[Coveralls] Outside the CI environment, not sending data.
FAIL: 1

As you can see from the examples above there are failures. However, we are only looking for failures caused by the code we modified/created in a given model. In this case, all code we have created/modified is not causing failures.

=== UI Testing ===

We concentrated our UI testing based on how changes to Code Climate issues affected the interface between callers and methods. Two main culprits were found.
# Change of ''Time.parse'' to ''Time.zone.parse''. While ''Time.parse'' returns an error for invalid or unknown times, ''Time.zone.parse'' returns ''nil'' for those types.
# Change of ''where().first'' to ''find_by()'' query. Using ''where().first'' returns empty records if record is not found, while ''find_by()'' returns ''nil'' if there was no match.
Note both of the above changes are well described in the [http://wiki.expertiza.ncsu.edu/index.php?title=E1920_Fix_Code_Climate_Issues#Most_Common_Issues_Reported_by_Code_Climate Most Common Issues Reported by Code Climate] section above. The section describes how such cases must be handled properly.

The user interface testing concentrated on three type of user stories.
# General functionality, could users still access the basic menu items from before.
# Test time functionality, such as sorting based on timestamp.
# Test searching functionality (involving all changes of ''where().first'' to ''find_by()'').
UI testing helped us revealed all the problems that were introduced along with our fixes and running through UI live demos ensured that we have fully functioning and properly working Expertiza app.

== Conclusion ==

Talk about conclusion.

== Team Contacts and Contribution ==

We have 3 (three) members in our team and 1 (one) mentor was assigned to us. For any project-related questions/concerns please contact us:

<ul>
<li> Christopher Adkins - cladkins@ncsu.edu
<li> George Hugh - gshugh@ncsu.edu
<li> Nikolay G. Titov - ngtitov@ncu.edu
<li> Zachariah Mathews (mentor) - zmathew@ncsu.edu
</ul>

If you have questions or concerns related to a specific file that was improved/modified by our team, please contact an engineer who worked on the file based on the [https://docs.google.com/spreadsheets/d/1bX2XizitGGoajFT6Br_y6MQjAwBCsX5WCVlx3xg8Jp8/edit?ts=5c87a06c#gid=0 Assignment Grid] we created to keep track of our progress and contribution. Please CC in email all team members and our mentor.

==References==
* Ruby [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/InverseOf]
* CodeClimate [https://docs.codeclimate.com/docs]
* Expertiza [https://github.com/expertiza/expertiza#expertiza]
* E. F. Gehringer, L. M. Ehresman, S. G. Conger and P. A. Wagle, "Work in Progress: Reusable Learning Objects Through Peer Review: The Expertiza Approach," Proceedings. Frontiers in Education. 36th Annual Conference, San Diego, CA, 2006, pp. 1-2. [http://ieeexplore.ieee.org.prox.lib.ncsu.edu/stamp/stamp.jsp?tp=&arnumber=4117076&isnumber=4116830]
* The ''has_many'' Association [https://guides.rubyonrails.org/association_basics.html#the-has-many-association]
* Module ActiveRecord::Associations::ClassMethods Options [https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many-label-Options]
* TimeZone Class [https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Rails/TimeZone]