Quality Assurance Guide (QAG)

The QAG was created by Digitalis Informatica as a guide to validate all technological software projects.

The QAG focuses on a number of indicators, best practices, and technologies that are used to provide a pattern of quality to all projects that state to be QAG compliant.

QAG in detail

Let's see all items that the QAG specifies

Software products

QAG specifies that a number of software products must be used for determined goals by all QAG compliant projects.

Maven

Maven is a technical project management tool. It allows to automate a set of steps in project building, deploying, documentation and quality assurance.
Maven adds to projects a set of conventions to every project it manages.

In regard do the QAG it is relevant to name the automation of Unit tests in every build, and the code coverage report.
All JUnit implemented tests are ran at every build after compilation, and before the build process.
A build will only be generated if the test suite ran successfully. This provides an early and automated quality check to every change a developer makes to the project.

The code coverage report (Cobertura), can be generated along with the documentation site for the project.

Maven Cobertura report sample

This report shows in detail the percentages of code coverage in a top down view starting in main packages and drilling down to inner packages, classes and every line of code within the project classes.\n This helps the developer to build tests that validate every line of code that the project has, and thus, map every functionality proper behavior after each code change.

Mandatory best practices

These are mandatory best practices that QAG forces the projects to comply.

Comments

All code must be carefully commented. The best practices defined for JavaDoc documentation generation should be validated, and all relevant code logic must also be documented. \n All the main Java IDEs allow us to configure them to consider missing of erroneous JavaDoc comments to be considered as errors. It's usage is highly encouraged! \n The Eclipse bundled in the Digitalis SDK allows automatic validation of all JavaDoc tags.

Advised Patterns and best practices

Several others patterns and best practices are very much advised by QAG. These are not mandatory for all projects since, now and again, common sense and practicality weight more than the use of some of these points. Nevertheless they must be taken very seriously on all QAG projects and are used in the majority of them.

SoC Separation of concerns

It's definition can be viewed here.

Maven imposes this, witch is another advantage of it's use. It does so mainly through the following features or imposed limitations:

  • All maven projects can only reference in their code classes that are directly reference by them as dependency projects. This is a declaration of the projects concerns and their extension. It is very usefully to have Maven monitoring this use, preventing us from go beyond our defined boundaries.
  • One sometimes annoying feature of Maven is not allowing circular dependencies of projects.
    We cannot declare project A as depending on project B if project B already depends of project A. This is not a technical limitation, but a self imposed rule for all projects.

These features act as constant monitoring automated tasks that prevent the commonly called Spaghetti code.

Code by Interface

It's definition is simple:

  • Define every functionality with an interface (i.e. ISomeFuncionality).
  • Implement as many implementation as needed by implementing the previous interface (i.e. FuncionalityFirstImpl, FuncionalitySecondImpl)
  • Always reference the implementing classes by interfaces typed instances \
    public ISomeFuncionality getFunc() {
        return new FuncionalityFirstImpl();
    };
IoC Inversion of Control

Inversion of Control and Dependency Injection are the glue that binds all modules and functionalities together. It is a vast topic, which you can read more in the IoC Utils project, our IoC implementation wrapper.

Documentation

The use of Maven is very much present is this section of QAG.

Maven Reports

Several of Maven's reports are mandatory by the definition of QAG.

Here is the full list of them:

  • Dependencies: List of dependencies of the project
  • Issue Tracking: The system that supports issues relative to this project
  • Project License: The license that regulates this project
  • Project Team: The list of the developers of the project and their contact
  • Source Repository: The source control repository
  • Cobertura Test Coverage: Coverage of code protected by automated tests (must always be a value between 80 and 100%)
  • CPD Report: Copy paste code detector
  • JavaDocs: API Documentation if the common JavaDoc format for all code
  • Maven Surefire Report: Report on the result of all automated tests
  • PMD Report: Analyses the code to find mistakes of bad uses. This list should always return zero warnings.
  • Source Xref: Browse the full source code of the project in linked HTML representations of it.
  • Tag List: A list of Tags (normally tasks or reminders) in your code. A stable project must normally have a very low count of these TAGs.
  • Test JavaDocs: API documentation of the automated test code in JavaDoc
  • Test Source Xref: Browse the full source code of the automated tests in linked HTML representations of it.
Other mandatory sections

Other than the previous automatically generated Maven reports a few sections must always exist in QAG projects.

User Guide

Complete instructions of what the project provides, and how to use it.
For simple projects a single page may suffice. For complex APIs and other large projects, a complete multi-paged User Guide, complete with all relevant features usage description should be published.

FAQ

The typical Frequently answered Questions.

Download

Easy access to the current and relevant previous versions.
By means of the Digitalis Maven Repository, all existing versions are always accessible and this should be referenced in the page.

Sample Application

All projects that represent an API or reusable component or library, should include a sample application to download and try out.
According to the difficulty of use of the project's functionalities, so should the sample application be more or less thorough.

Naturally that, if the API is simple enough to configure, deploy and use, simple instructions can suffice, and a sample application is replaces by a sample usage section.

Availability of code and distributions

As stated in the download item, all distribution versions should be available. Here we state that so should the projects code, when we speak of an open-source project.
All code for all releases and other functionalities, a Version Control system should be provided.

Latest source code always available

The latest release code should be directly available in zip format, in the download page, for easy access.

Latest release available by Maven repositories and by direct site download at all times

The latest release should be directly available, in the download page, for easy access.

All sample programs must have their source code and executable form available in the download section of the site