How to evolve an application to make it more robust and maintainable - Presentation

Foreword

Recently I was shown an application that had been created quite recently but which looked like an application from ten or fifteen years ago. After that I thought it would be interesting to try to make an application similar to the one I was shown evolve towards a quality architecture. Through this first article we will present the application (cf link to GitHub) for which we will make a state of the art, and we will define the axes of improvement that we will set up in the next articles of this series.

Presentation of the application

Functionally

The API allows to manage interviews between a manager and his mentees. The management rules are:

An interview:

• concerns a manager and an employee.
• has a form

A form:

• has a simple answer to each question. An answer can be entered in a text field.
• can be associated with a note that only the manager can see

A manager

• can create an interview
• can create a note visible only to him/her

Technically

The application is written in java 11, it was generated by the Spring initilaizer (). The database is H2 (problem that we will fix quickly)

The problems

A quick look at the code shows several types of problems:

• documentation problems
• quality problems
• architecture problems

Documentation problems

an empty readme

By convention the README is the entry point to any application; it should allow newcomers to understand, launch and test the application. It should therefore contain in addition to a quick presentation of the API

• Instructions for compiling the code
• Instructions for running the application locally
• Data to use locally if needed

no swagger (or other)

In order to test an API easily it is necessary to have a tool to run queries, which can range from Postman scripts to a fully integrated Swagger.

Quality problems

no tests

The project contains only one test, the one generated by the Spring initializer. We agree that it is logically impossible for a test to ensure that no bugs are present. It allows us to verify at least that the application does what it should do. In this case, without tests, this minimum is not guaranteed and any re-factorisation is therefore inadvisable since any regression could not be identified. For an existing project where there is a lack of testing it is possible to start with component testing to cover as much code as possible;

Lack of settings and CI(CD)

CI/CD, Continuous Integration and Continuous Deployment, is an essential element in monitoring the functionality of code. Among other things, it allows:

• to build the code
• to launch the tests by distinguishing the tests by type
• run tests for code quality with plugins like Checkstyle or Spotless
• check the coverage of the code
• create Docker images
• to deploy the api on a given environment

The CI/CD can be launched after a push to a branch, the creation of the pull request (or merge request), the merge on the reference branch.

Lack of tools to check the quality of the code.

The quality of the code can be defined by its readability and the respect of programming rules (whether they are specific to the company or defined with a tool such as SonarQube). The code review is there to validate these points, but it can be facilitated by the implementation of tools such as:

• the use of plugins (Maven or Gradle) like Checkstyle which will be launched during builds
• the use of a style code (like google-java-format or Spotless) in the IDE to ensure proper formatting
• Using a plugin such as SonarLint to check the quality of the code against the company’s quality gates

Architectural problems

Use of a H2 database

The first point is more of an oversight on our part when creating the basic application: it is the use of the H2 database and not the use of a database like Postgresql or Mysql. It goes without saying that the use of an embedded database is not compatible with the use of an application (API) in production.

Use of a layered architecture \

the use of a layered architecture favours database-based modelling. This prevents :

• parallelize development: entities and repositories must be created for this to work.
• The database schema is often used as the basis for the business model

Mix of business domains

Looking at the code, it appears that the different business lines: people management, forms management and notes management are all linked. This mixture of functions reduces the robustness of the code; the greater the number of functions, the greater the number of reasons to change the code and therefore the greater the risk of regressions. The application of the “single responsibility” principle would already allow splitting some classes

Upcoming articles

The issues identified in this article will be the subject of a series of articles that will outline how to correct them and enable us to improve our API. The first articles will cover, among other things

• The implementation of tests
• Setting up a hexagonal architecture with ArchUnit
• Setting up SonarQube
• The implementation of quality and correction of the code smell

If you are reading this sentence, it means that you have read this article in its entirety, and I thank you for that because this is my first article. If you have any remarks on the content or the form, you can leave a comment…it is by exchanging that we progress.

Written by : Emmanuel Quinton Review by : Daniele Cremonini