<commit_before>/*
 * Copyright 2017 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.errorprone.bugpatterns.argumentselectiondefects;

import static com.google.errorprone.BugPattern.Category.JDK;
import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;

import com.google.common.annotations.VisibleForTesting;
import com.google.errorprone.BugPattern;
import com.google.errorprone.VisitorState;
import com.google.errorprone.bugpatterns.BugChecker;
import com.google.errorprone.bugpatterns.BugChecker.MethodInvocationTreeMatcher;
import com.google.errorprone.bugpatterns.BugChecker.NewClassTreeMatcher;
import com.google.errorprone.fixes.SuggestedFix;
import com.google.errorprone.matchers.Description;
import com.google.errorprone.names.NamingConventions;
import com.google.errorprone.names.NeedlemanWunschEditDistance;
import com.google.errorprone.util.ASTHelpers;
import com.sun.source.tree.MethodInvocationTree;
import com.sun.source.tree.NewClassTree;
import com.sun.tools.javac.code.Symbol.MethodSymbol;
import java.util.function.Function;

/**
 * Checks the lexical distance between method parameter names and the argument names at call sites.
 * If another permutation of the arguments produces a lower distance then it is possible that the
 * programmer has accidentally reordered them.
 *
 * <p>TODO(andrewrice) add reference to paper here when we have a name
 *
 * <p>Terminology:
 *
 * <ul>
 *   <li>Formal parameter - as given in the definition of the method
 *   <li>Actual parameter - as used in the invocation of the method
 *   <li>Parameter - either a formal or actual parameter
 * </ul>
 *
 * @author <EMAIL> (<NAME>)
 */
@BugPattern(
  name = "ArgumentSelectionDefectChecker",
  summary = "Arguments to this method call may be in the wrong order",
  explanation =
      "If permuting the arguments of a method call means that the argument names are a better "
          + "match for the parameter names than the original ordering then this might indicate "
          + "that they have been accidentally swapped.  There are also legitimate reasons for the "
          + "names not to match such as when rotating an image (swap width and height).  In this "
          + "case we would recommend annotating the names with a comment to make the deliberate "
          + "swap clear to future readers of the code. Argument names annotated with a comment "
          + "containing the parameter name will not generate a warning.",
  category = JDK,
  severity = WARNING
)
public class ArgumentSelectionDefectChecker extends BugChecker
    implements MethodInvocationTreeMatcher, NewClassTreeMatcher {

  private final ArgumentChangeFinder argumentchangeFinder;

  public ArgumentSelectionDefectChecker() {
    this(
        ArgumentChangeFinder.builder()
            .setDistanceFunction(buildDefaultDistanceFunction())
            .addHeuristic(new LowInformationNameHeuristic())
            .addHeuristic(new PenaltyThresholdHeuristic())
            .addHeuristic(new EnclosedByReverseHeuristic())
            .addHeuristic(new CreatesDuplicateCallHeuristic())
            .addHeuristic(new NameInCommentHeuristic())<commit_msg>Update summary of ArgumentSelectionDefectChecker to make it clearer that adding comments to names is a viable fix<commit_after>/*
 * Copyright 2017 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.errorprone.bugpatterns.argumentselectiondefects;

import static com.google.errorprone.BugPattern.Category.JDK;
import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;

import com.google.common.annotations.VisibleForTesting;
import com.google.errorprone.BugPattern;
import com.google.errorprone.VisitorState;
import com.google.errorprone.bugpatterns.BugChecker;
import com.google.errorprone.bugpatterns.BugChecker.MethodInvocationTreeMatcher;
import com.google.errorprone.bugpatterns.BugChecker.NewClassTreeMatcher;
import com.google.errorprone.fixes.SuggestedFix;
import com.google.errorprone.matchers.Description;
import com.google.errorprone.names.NamingConventions;
import com.google.errorprone.names.NeedlemanWunschEditDistance;
import com.google.errorprone.util.ASTHelpers;
import com.sun.source.tree.MethodInvocationTree;
import com.sun.source.tree.NewClassTree;
import com.sun.tools.javac.code.Symbol.MethodSymbol;
import java.util.function.Function;

/**
 * Checks the lexical distance between method parameter names and the argument names at call sites.
 * If another permutation of the arguments produces a lower distance then it is possible that the
 * programmer has accidentally reordered them.
 *
 * <p>TODO(andrewrice) add reference to paper here when we have a name
 *
 * <p>Terminology:
 *
 * <ul>
 *   <li>Formal parameter - as given in the definition of the method
 *   <li>Actual parameter - as used in the invocation of the method
 *   <li>Parameter - either a formal or actual parameter
 * </ul>
 *
 * @author <EMAIL>.com (<NAME>)
 */
@BugPattern(
  name = "ArgumentSelectionDefectChecker",
  summary = "Arguments are in the wrong order or could be commented for clarity.",
  explanation =
      "If permuting the arguments of a method call means that the argument names are a better "
          + "match for the parameter names than the original ordering then this might indicate "
          + "that they have been accidentally swapped.  There are also legitimate reasons for the "
          + "names not to match such as when rotating an image (swap width and height).  In this "
          + "case we suggest annotating the names with a comment to make the deliberate "
          + "swap clear to future readers of the code. Argument names annotated with a comment "
          + "containing the parameter name will not generate a warning.",
  category = JDK,
  severity = WARNING
)
public class ArgumentSelectionDefectChecker extends BugChecker
    implements MethodInvocationTreeMatcher, NewClassTreeMatcher {

  private final ArgumentChangeFinder argumentchangeFinder;

  public ArgumentSelectionDefectChecker() {
    this(
        ArgumentChangeFinder.builder()
            .setDistanceFunction(buildDefaultDistanceFunction())
            .addHeuristic(new LowInformationNameHeuristic())
            .addHeuristic(new PenaltyThresholdHeuristic())
            .addHeuristic(new EnclosedByReverseHeuristic())
            .addHeuristic(new CreatesDuplicateCallHeuristic())
            .addHeuristic(new NameInCommentHeuristic())
{'fraction_non_alphanumeric': 0.07205298013245033, 'fraction_numerical': 0.002119205298013245, 'mean_word_length': 4.140231449965963, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2376995', 'n_tokens_mistral': 2019, 'n_tokens_neox': 1958, 'n_words': 707}