001/*
002 * SonarQube, open source software quality management tool.
003 * Copyright (C) 2008-2014 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * SonarQube 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 * SonarQube 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 */
020
021package org.sonar.api.server.debt;
022
023import javax.annotation.CheckForNull;
024
025/**
026 * Function used to calculate the remediation cost of an issue. See {@link Type} for details.
027 * <p>The coefficient and offset involved in the functions are durations. They are defined in hours, minutes and/or
028 * seconds. Examples: "5min", "1h 10min". Supported units are "d" (days), "h" (hour), and "min" (minutes).</p>
029 *
030 * @since 4.3
031 */
032public interface DebtRemediationFunction {
033
034  enum Type {
035
036    /**
037     * The cost to fix an issue of this type depends on the magnitude of the issue.
038     * For instance, an issue related to file size might be linear, with the total cost-to-fix incrementing
039     * (by the coefficient amount) for each line of code above the allowed threshold.
040     * The rule must provide the "effort to fix" value when raising an issue.
041     */
042    LINEAR(true, false),
043
044    /**
045     * It takes a certain amount of time to deal with an issue of this type (this is the offset).
046     * Then, the magnitude of the issue comes in to play. For instance, an issue related to complexity might be linear with offset.
047     * So the total cost to fix is the time to make the basic analysis (the offset) plus the time required to deal
048     * with each complexity point above the allowed value.
049     * <p>
050     * <code>Total remediation cost = offset + (number of noncompliance x coefficient)</code>
051     * </p>
052     * <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.
053     * If you set the rule threshold to 20, and you have a paragraph with a complexity of 27, you have 7 points of complexity
054     * to remove. Internally, this is called the Effort to Fix. In that case, if you use the LINEAR_OFFSET configuration
055     * with an offset of 4h and a remediation cost of 1mn, the technical debt for this issue related to a
056     * too-complex block of code will be: (7 complexity points x 1min) + 4h = 4h and 7mn
057     * </p>
058     */
059    LINEAR_OFFSET(true, true),
060
061    /**
062     * The cost to fix all the issues of the rule is the same whatever the number of issues
063     * of this rule in the file. Total remediation cost by file = constant
064     */
065    CONSTANT_ISSUE(false, true);
066
067    private final boolean usesCoefficient;
068    private final boolean usesOffset;
069
070    Type(boolean usesCoefficient, boolean usesOffset) {
071      this.usesCoefficient = usesCoefficient;
072      this.usesOffset = usesOffset;
073    }
074
075    public boolean usesCoefficient() {
076      return usesCoefficient;
077    }
078
079    public boolean usesOffset() {
080      return usesOffset;
081    }
082  }
083
084  Type type();
085
086  /**
087   * Non-null value on {@link Type#LINEAR} and {@link Type#LINEAR_OFFSET} functions, else {@code null}.
088   */
089  @CheckForNull
090  String coefficient();
091
092  /**
093   * Non-null value on {@link Type#LINEAR_OFFSET} and {@link Type#CONSTANT_ISSUE} functions, else {@code null}.
094   */
095  @CheckForNull
096  String offset();
097
098}