Week 9 - Code Quality I#
Today’s learning objectives
Topics for today:
Concepts of code quality
Assessing code quality
Understand the process of refactoring
Write a first test
What to expect By the end of the seminar we would like you to have identified possible improvements in the quality of your software and started writing a test.
📆 Seminar schedule#
Welcome!
Reminder of the Code of Conduct
Discuss previous assignments [10 min]
Reflection on software quality [45 min]
Introduce assignments [5 min]
Work on assignments [50 min]
🙋 Discussion and questions#
Reflection on software quality#
The FAIR principles for research software do not provide a set of best practices that ensure a minimum level of code quality. Closest comes the Reusable section, which states that software is both usable (can be executed) and reusable (can be understood, modified, built upon, or incorporated into other software), with the subcriteria R3: Software meets domain-relevant community standards.
Warning
Questions:
What would you consider clean and quality code?
What would you consider bad code?
Writing good quality and clean code ensures that your software is easy to understand, maintain, extend, and reuse. The Code Refinery introduced a couple of practical lessons to improve and maintain the quality of code by
Writing modular code with small and pure functions
Writing readable code by following style guides (see also Week 6)
Using defensive programming
Writing (automated) tests
In addition, we would add error handling for code robustness and logging for code debugging.
Tip
A good example: Example of research software from the eScience Center that implements code quality checks: matchms/matchms.
Note
Additional information The University of Utrecht has offered a module on Code Quality during a workshop on software reproducibility. Have a look at the slides for some general tips and common best practices:
We identified three additional resources that provide some standards on code quality criteria and best practices for (research) software:
The OpenSSF Best Practices Badge Program offers a shared quality standard for open software. Projects can voluntarily self-certify, at no cost, by using a web application to explain how they follow each of the best practices. Once completed, you are provided with a badge to add to your repository.
The European Open Science Cloud (EOSC) Association has created tools and documentation for setting software quality standards for research. They have developed a minimum viable set of quality requirements for software.
The International Standard Organisation (ISO) has issued a standard (ISO 9126) for software quality criteria (not specific to research software). An overview of the standard with descriptions, can be found here.
Note
Diagram 
Assignments for Wednesday 17th of May#
The goal of the this week’s challenges and assignments is to identify ways to improve the quality of your code and start with refactoring and testing a small part.
Tip
đź’ˇ Tip: Add the FAIR card to your Github board to as a reference on writing tests for research software.
FAIR card - Testing#
_Essential_
- [ ] Document how users can verify the proper functioning of the software
- [ ] Document verification for user installation and software execution
_Recommended_
- [ ] [Defensive programming](https://swcarpentry.github.io/python-novice-inflammation/10-defensive/index.html)
- [ ] Test your software with [integration tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-integrationtest.html) and [unit tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-unittest.html)
- [ ] Make use of [Continuous Integration](https://the-turing-way.netlify.app/reproducible-research/ci/ci-options.html)
- [ ] Code coverage check ([Codecov](https://about.codecov.io/), [Sonarcloud](https://sonarcloud.io/), [Travis](https://www.travis-ci.com/)).
- [ ] Ensure a minimum test coverage of 70%.
Assignment 1#
We will conduct a code review together and assess a software project for possible improvements in code quality.
Example repo: anailil/FAIR-well-logs Context about the project: https://anailil.github.io/Quick-Visualisation-of-Geophysical-Borehole-Data/
From the ISO standard for software criteria, let’s review the code with a focus on the following criteria:
Accuracy: Does the code provide the right or agreed-upon results or effects?
Maturity: Are inputs and types checked?
Resource Utilization: How does the performance scale with the dataset size?
Analyzability: How are errors and exceptions handled?
Changeability: How easy is it to extend the code with new features?
Stability: How easy is it to make changes?
Testability: How can the code be tested?
In addition, here a some code smells to look out for:
Important
Rigidity. The software is difficult to change. A small change causes a cascade of subsequent changes.
Fragility. The software breaks in many places due to a single change.
Immobility. You cannot reuse parts of the code in other projects because of involved risks and high effort.
Needless Complexity.
Needless Repetition.
Opacity. The code is hard to understand.
Tip
💡 Many books, articles, and blogs have been written about clean code. For a succinct list, we like The Zen of Python and a summary of Uncle Bob’s book on clean code. The Turing Way also provides a good checklist for a Code Review.
Assignment 2#
Now, evaluate your own project following the software quality characteristics we discussed in Assignment 1.
Read the following content on software quality: https://www2.cs.sfu.ca/~cameron/Teaching/473/quality_characteristics.html
Make a list of quality “subcharacteristics” as described in the article you feel are relevant in the current phase of your project.
Consider for these priorities those things you will address in your next release.
Here is an example to help you get started:
Note
Must address this year
Suitability: The capability of the software to provide an adequate set of functions for specified tasks and user objectives.
…
Should address this year
Resource Utilization: The capability of the software to use appropriate resources in an appropriate time when the software performs its function under stated condition.
…
Could address if I get feedback from users/developers
Changeability: The capability of the software product to enable a specified modification to be implemented.
…
Won’t address for now
Time Behavior: The capability of the software to provide appropriate response and processing times and throughput rates when performing its function under stated conditions.
…
Tip
đź’ˇ Tip: You can be more specific by defining specific tasks and objectives. Or revisit your project features backlog and reuse what you have written there.
Assignment 3#
Note
Code refactoring
In computer programming and software design, code refactoring is the process of restructuring existing computer code — changing the factoring — without changing its external behavior. Refactoring is intended to improve the design, structure, and/or implementation of the software (its non-functional attributes), while preserving its functionality.
Refactoring is often an ongoing process to improve your code. In order to refactor a piece of code and ensure that its functionality and external behaviour won’t change, we can make use of tests. A good approach to follow:
Identify a small piece of code you want to improve.
Ensure the code is in the form of a small function (or class method).
Add (or update) tests that define the expected behaviour of the function.
Verify the passing of the tests.
Refactor the function to improve the quality.
Verify the passing of the tests.
This process is a good strategy to slowly improve the coverage of your code with tests. Each time you refactor a piece of code, add a test that captures the correct behaviour. Follow the Boy Scouts rule: Leave the campground cleaner than you found it.
Tip
đź’ˇ Tips:
Review the Code Refinery lesson on testing
Link to tips about the process of refactoring
Code refactoring best practices for Python
Examples of bad code
Bad code to better code, an example.