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 gap multiplier and base effort 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). 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 gap multiplier amount) for each line of code above the allowed threshold. 039 * The rule must provide the "gap" 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 gap multiplier). 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 base effort) plus the time required to deal 047 * with each complexity point above the allowed value. 048 * <p> 049 * <code>Total remediation cost = base effort + (number of noncompliance x gap multiplier)</code> 050 * 051 * <p>The rule must provide the "gap" 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 Gap. In that case, if you use the LINEAR_OFFSET configuration 054 * with an base effort of 4h and a remediation cost of 1mn, the effort for this issue related to a 055 * too-complex block of code will be: (7 complexity points x 1min) + 4h = 4h and 7mn 056 * 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 usesGapMultiplier; 067 private final boolean usesBaseEffort; 068 069 Type(boolean usesGapMultiplier, boolean usesBaseEffort) { 070 this.usesGapMultiplier = usesGapMultiplier; 071 this.usesBaseEffort = usesBaseEffort; 072 } 073 074 /** 075 * @deprecated since 5.5, replaced by {@link #usesGapMultiplier()} 076 */ 077 @Deprecated 078 public boolean usesCoefficient() { 079 return usesGapMultiplier(); 080 } 081 082 /** 083 * @since 5.5 084 */ 085 public boolean usesGapMultiplier() { 086 return usesGapMultiplier; 087 } 088 089 /** 090 * @deprecated since 5.5, replaced by {@link #usesBaseEffort()} 091 */ 092 @Deprecated 093 public boolean usesOffset() { 094 return usesBaseEffort(); 095 } 096 097 /** 098 * @since 5.5 099 */ 100 public boolean usesBaseEffort() { 101 return usesBaseEffort; 102 } 103 104 } 105 106 /** 107 * @since 5.5 108 */ 109 Type type(); 110 111 /** 112 * @deprecated since 5.5, replaced by {@link #gapMultiplier()} 113 */ 114 @Deprecated 115 @CheckForNull 116 String coefficient(); 117 118 /** 119 * Non-null value on {@link Type#LINEAR} and {@link Type#LINEAR_OFFSET} functions, else {@code null}. 120 * 121 * @since 5.5 122 */ 123 @CheckForNull 124 String gapMultiplier(); 125 126 /** 127 * @deprecated since 5.5, replaced by {@link #baseEffort()} 128 */ 129 @Deprecated 130 @CheckForNull 131 String offset(); 132 133 /** 134 * Non-null value on {@link Type#LINEAR_OFFSET} and {@link Type#CONSTANT_ISSUE} functions, else {@code null}. 135 * 136 * @since 5.5 137 */ 138 @CheckForNull 139 String baseEffort(); 140 141}