Student-friendly pipeline documentation

This repository shows an example of a Github workflow that evaluates the quality of a Java project and reports:

• Design metrics
• Code style
• Code smells

The workflow works by creating a report for pull request submitted to the repository. For example, see the pull request in this repository.

The usage section can be seen here

The feedback report section can be seen here

Usage

The simplest way to use the workflow is to:

1. Create a new repository
2. Copy the content of this repository into the new one
3. Submit a commit to the main branch
4. Create a Pull Request:
   • Create a new branch
   • Change the code
   • Commit to the new branch
   • Create a Pull Request from the new branch to the main one

Alternatively you can set up your repository from scratch by adding configurations to your Maven project:

• ROOT/.github/workflows/report.yml: The workflow configuration file for GitHub Actions
• ROOT/pom.xml: Add 2 plugins to your pom.xml configuration file
• ROOT/checkstyle.xml: Add the Checkstyle configuration file for the Checkstyle Maven plugin

Workflow configuration

The report.yml file needs to be placed at this path from the root of your project so it gets recognized by Github: ./.github/workflows)

This file is available at the same path on this repository.

Here is the explanation of the report.yml file

The pipeline is divided into 3 jobs:

• build
• upload-designite-artifact
• report

---

build

actions used: actions/checkout@v3, actions/setup-java@v3

description:

The purpose of this job is to allow the user to know directly if the code builds, tests pass and a package can be created before doing the other jobs.

---

upload-designite-artifact

actions used: GuillaumeFalourd/clone-github-repo-action@v2, actions/upload-artifact@v3

description:

The purpose of this job is to upload the designite jar to execute the tool in the last job

---

report

actions used: actions/checkout@v3, actions/setup-java@v3, actions/download-artifact@v3, robinraju/[email protected], montudor/action-zip@v1, search-rug/[email protected], thollander/actions-comment-pull-request@v1

description:

This job is the core of the pipeline. It will execute the Maven goals of the Maven plugins (jacoco-maven-plugin, maven-checkstyle-plugin) in order to generate the analytic files.

It will download the Designite exectuable artifact and execute it against the project to generate the analytic files.

Regarding the metrics, to use CK it will clone its repository, since it is a Maven project it will install it, and finally execute its goal on the current project, this process is due to the way described by the CK README file to use the tool, eventually the analytic files are generated. To use the JaSoMe tool, the process is to download the release, unzip it and execute it against the project to generate the analytic files.

Now that all the files have been generated. The action corresponding to this repository will be used to aggregate and format the information into a single output that will represent a report in a Markdown formatted String variable.

The Markdown formatted String is used with an action that will comment the pull request.

Maven configuration

Your project should include 2 Maven plugins in the build tag of the pom.xml file.

You can refer to the pom.xml file on this repository. Here is a look at the configuration of this pom.xml file:

• jacoco-maven-plugin (verion: 0.8.7, group-id: org.jacoco)

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.7</version>
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The first goal, "prepare-agent", will prepare the JaCoCo runtime agent to record the execution data.
The second goal, "report", will use the execution data recorded to generate code coverage reports.
This second goal is tied to the "test" phase of the Maven lifecycle, this means that the goal will be trigger of the compilation of this phase.
The test coverage report can be found at target/site/jacoco/index.html.

• maven-checkstyle-plugin (version: 3.1.2, group-id: org.apache.maven.plugins)

<plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-checkstyle-plugin</artifactId>
      <version>3.1.2</version>
      <configuration>
        <configLocation>checkstyle.xml</configLocation>
        <encoding>UTF-8</encoding>
      </configuration>
</plugin>

Checkstyle configuration

The checkstyle.xml needs to be placed at the root of your project. This file is available at the same path on this repository.

---

Feedback Report

The feedback report provides insights upon the code quality of the project implemented the workflow. You will find insights about encapsulation, inheritance, coupling, cohesion among other aspects of Object Oriented Programming.

Design Metrics

Metrics are quantitave measures that give you insights upon different aspects of your code quality. The metric section is divided into 2 categories, class-level metrics and method-level metrics.

Class Level

Metric	Category	Range	Description	Interpretation
FAN-IN	Coupling	0..N	The number of input dependencies a class has	High value: A class that is used a lot by other classes. It is tightly coupled to the rest of the design. This could lead to knock-on effects.
FAN-OUT	Coupling	0..N	The number of output dependencies a class has	High value: A class that uses a lot of other classes. It is a class prone to change.
TCC	Cohesion	0..1	TCC measures the cohesion of a class via direct connections between visible methods. A direct connection happens when these methods or their invocation trees access the same class variable.	High value: Many pairs of methods access the same class variable. A class that is cohesive.
Method Iheritance Factor (MIF)	Inheritance	0..1	MD = Methods defined PMI = Public methods inherited MIF = PMI / (PMI + MD)	Low value: A class that does not inherit a lot of methods. Questionable inheritance. High value: A class that inherits a lot of methods. Signs of reusability.
Public Attributes	Encapsulation	0..N	The number of fields that are visible (e.g. public)	High value: Many attributes are visible. It is a sign of poor design.
Method Hiding Factor (MHF)	Encapsulation	0..1	TNM = Total Number of Methods NVM = Non-Visible Methods MHF = NVM/TNM	High value: A class that has little public methods. The class has little access.

Method Level

Metric	Category	Range	Description	Interpretation
FAN-IN	Coupling	0..N	The number of input dependencies a method has	High value: A method that is used a lot by other methods. It is tightly coupled to the rest of the design. This could lead to knock-on effects.
FAN-OUT	Coupling	0..N	The number of output dependencies a method has	High value: A method that uses a lot of other methods. It is a method prone to change.
Total Lines of Code (TLOC)	Size	0..N	The total lines of code without comments and whitespaces.	High value: Large method. A method that can be hard to understand and to maintain. May be violating the Single Responsibility Principle.
Number of Parameters (NOP)	Readability	0..N	The number of parameters	High value: Long parameter list. A method that can be hard to understand and to maintain. The parameters can be misinterpreted or given in the wrong order. It may be a sign of low cohesion.
Nested Block Depth (NBD)	Complexity	1..N	The number of the maximum depth of nested block. If there is no nested block, the depth equals to 1.	High value: A method that contains deep nested blocks. A method that is complex. Harder to test all the cases of a method.
McCabe Cyclomatic Complexity	Complexity	1..N	Representation of the control flow as a graph (control flow graph) The control flow contains nodes (entry point, exit point, decision points) Nodes are connected by directed edges M = E - N +2P number of edges E number of nodes N number of connected components P (graph theory) Cyclomatic complexity of a linear control flow is always one.	High value: Many different paths exist in the same method. A method that is complex. Harder to test all the cases of a method.

---

Code Style

This list are all the issues selected to be reported by Checkstyle, a tool that automates the process of checking Java code. This selection is based on a paper that describes all Checkstyle code quality issues considered rekevant for computing undergraduates. See the reference below.
Oscar Karnalim, Simon, William Chivers, "Work-In-Progress: Code Quality Issues of Computing Undergraduates", ref

Code quality issues reported are split into 7 categories:

• Naming

  • AbstractClassName
  • ConstantName

• Sizes

  • ExecutableStatementCount
  • LineLength

• Whitespace

  • EmptyLineSeparator

• Blocks

  • EmptyBlock
  • EmptyCatchBlock
  • NeedBraces

• Coding

  • AvoidInlineConditionals
  • DeclarationOrder
  • EmptyStatement
  • MultipleVariableDeclarations
  • NestedForDepth
  • NestedIfDepth
  • NestedTryDepth
  • OneStatementPerLine
  • RequireThis
  • SimplifyBooleanExpression
  • SimplifyBooleanReturn
  • StringLiteralEquality
  • UnnecessaryParentheses
  • UnnecessarySemicolonAfterTypeMemberDeclaration

• Miscellaneous

  • ArrayTypeStyle

• Metrics

  • BooleanExpressionComplexity

---

Code Smells

Code smells are code structures that may suggest a refactoring. They are only warnings and it is up to the developer to interpret and decide if a refactoring is necessary.

You can check the definition of the Design smells at https://www.designite-tools.com/faq/

Design smells

There are 4 categories

Abstraction:

• Imperative Abstraction
• Multifaceted Abstraction
• Unnecessary Abstraction
• Unutilized Abstraction

Encapsulation

• Deficient Encapsulation
• Unexploited Encapsulation

Modularization

• Broken Modularization
• Cyclic-Dependent Modularization
• Insufficient Modularization
• Hub-like Modularization

Hierarchy

• Broken Hierarchy
• Cyclic Hierarchy
• Deep Hierarchy
• Missing Hierarchy
• Multipath Hierarchy
• Rebellious Hierarchy
• Wide Hierarchy

Implementation smells

• Complex Conditional
• Complex Method
• Empty catch clause
• Long Identifier
• Long Method
• Long Parameter List
• Long Statement
• Magic Number
• Missing default

---

References:

• Refactoring Guru
• Fan-in, Fan out
• High Fan-in vs High Fan out