001/* 002 * SonarQube 003 * Copyright (C) 2009-2016 SonarSource SA 004 * mailto:contact AT sonarsource DOT com 005 * 006 * This program is free software; you can redistribute it and/or 007 * modify it under the terms of the GNU Lesser General Public 008 * License as published by the Free Software Foundation; either 009 * version 3 of the License, or (at your option) any later version. 010 * 011 * This program is distributed in the hope that it will be useful, 012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 * Lesser General Public License for more details. 015 * 016 * You should have received a copy of the GNU Lesser General Public License 017 * along with this program; if not, write to the Free Software Foundation, 018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 019 */ 020package org.sonar.api.server.debt; 021 022import javax.annotation.CheckForNull; 023 024/** 025 * Function used to calculate the remediation cost of an issue. See {@link Type} for details. 026 * <p>The coefficient and offset involved in the functions are durations. They are defined in hours, minutes and/or 027 * seconds. Examples: "5min", "1h 10min". Supported units are "d" (days), "h" (hour), and "min" (minutes).</p> 028 * 029 * @since 4.3 030 */ 031public interface DebtRemediationFunction { 032 033 enum Type { 034 035 /** 036 * The cost to fix an issue of this type depends on the magnitude of the issue. 037 * For instance, an issue related to file size might be linear, with the total cost-to-fix incrementing 038 * (by the coefficient amount) for each line of code above the allowed threshold. 039 * The rule must provide the "effort to fix" value when raising an issue. 040 */ 041 LINEAR(true, false), 042 043 /** 044 * It takes a certain amount of time to deal with an issue of this type (this is the offset). 045 * Then, the magnitude of the issue comes in to play. For instance, an issue related to complexity might be linear with offset. 046 * So the total cost to fix is the time to make the basic analysis (the offset) plus the time required to deal 047 * with each complexity point above the allowed value. 048 * <p> 049 * <code>Total remediation cost = offset + (number of noncompliance x coefficient)</code> 050 * </p> 051 * <p>The rule must provide the "effort to fix" value when raising an issue. Let’s take as a example the “Paragraphs should not be too complex” rule. 052 * If you set the rule threshold to 20, and you have a paragraph with a complexity of 27, you have 7 points of complexity 053 * to remove. Internally, this is called the Effort to Fix. In that case, if you use the LINEAR_OFFSET configuration 054 * with an offset of 4h and a remediation cost of 1mn, the technical debt for this issue related to a 055 * too-complex block of code will be: (7 complexity points x 1min) + 4h = 4h and 7mn 056 * </p> 057 */ 058 LINEAR_OFFSET(true, true), 059 060 /** 061 * The cost to fix all the issues of the rule is the same whatever the number of issues 062 * of this rule in the file. Total remediation cost by file = constant 063 */ 064 CONSTANT_ISSUE(false, true); 065 066 private final boolean usesCoefficient; 067 private final boolean usesOffset; 068 069 Type(boolean usesCoefficient, boolean usesOffset) { 070 this.usesCoefficient = usesCoefficient; 071 this.usesOffset = usesOffset; 072 } 073 074 public boolean usesCoefficient() { 075 return usesCoefficient; 076 } 077 078 public boolean usesOffset() { 079 return usesOffset; 080 } 081 } 082 083 Type type(); 084 085 /** 086 * Non-null value on {@link Type#LINEAR} and {@link Type#LINEAR_OFFSET} functions, else {@code null}. 087 */ 088 @CheckForNull 089 String coefficient(); 090 091 /** 092 * Non-null value on {@link Type#LINEAR_OFFSET} and {@link Type#CONSTANT_ISSUE} functions, else {@code null}. 093 */ 094 @CheckForNull 095 String offset(); 096 097}