clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.rst

   1 .. title:: clang-tidy - readability-suspicious-call-argument
   2
   3 readability-suspicious-call-argument
   4 ====================================
   5
   6 Finds function calls where the arguments passed are provided out of order,
   7 based on the difference between the argument name and the parameter names
   8 of the function.
   9
  10 Given a function call ``f(foo, bar);`` and a function signature
  11 ``void f(T tvar, U uvar)``, the arguments ``foo`` and ``bar`` are swapped if
  12 ``foo`` (the argument name) is more similar to ``uvar`` (the other parameter)
  13 than ``tvar`` (the parameter it is currently passed to) **and** ``bar`` is
  14 more similar to ``tvar`` than ``uvar``.
  15
  16 Warnings might indicate either that the arguments are swapped, or that the
  17 names' cross-similarity might hinder code comprehension.
  18
  19 .. _heuristics:
  20
  21 Heuristics
  22 ----------
  23
  24 The following heuristics are implemented in the check.
  25 If **any** of the enabled heuristics deem the arguments to be provided out of
  26 order, a warning will be issued.
  27
  28 The heuristics themselves are implemented by considering pairs of strings, and
  29 are symmetric, so in the following there is no distinction on which string is
  30 the argument name and which string is the parameter name.
  31
  32 Equality
  33 ^^^^^^^^
  34
  35 The most trivial heuristic, which compares the two strings for case-insensitive
  36 equality.
  37
  38 .. _abbreviation_heuristic:
  39
  40 Abbreviation
  41 ^^^^^^^^^^^^
  42
  43 Common abbreviations can be specified which will deem the strings similar if
  44 the abbreviated and the abbreviation stand together.
  45 For example, if ``src`` is registered as an abbreviation for ``source``, then
  46 the following code example will be warned about.
  47
  48 .. code-block:: c++
  49
  50     void foo(int source, int x);
  51
  52     foo(b, src);
  53
  54 The abbreviations to recognise can be configured with the
  55 :ref:`Abbreviations<opt_Abbreviations>` check option.
  56 This heuristic is case-insensitive.
  57
  58 Prefix
  59 ^^^^^^
  60
  61 The *prefix* heuristic reports if one of the strings is a sufficiently long
  62 prefix of the other string, e.g. ``target`` to ``targetPtr``.
  63 The similarity percentage is the length ratio of the prefix to the longer
  64 string, in the previous example, it would be `6 / 9 = 66.66...`\%.
  65
  66 This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
  67 The default bounds are: below `25`\% dissimilar and above `30`\% similar.
  68 This heuristic is case-insensitive.
  69
  70 Suffix
  71 ^^^^^^
  72
  73 Analogous to the `Prefix` heuristic.
  74 In the case of ``oldValue`` and ``value`` compared, the similarity percentage
  75 is `8 / 5 = 62.5`\%.
  76
  77 This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
  78 The default bounds are: below `25`\% dissimilar and above `30`\% similar.
  79 This heuristic is case-insensitive.
  80
  81 Substring
  82 ^^^^^^^^^
  83
  84 The substring heuristic combines the prefix and the suffix heuristic, and tries
  85 to find the *longest common substring* in the two strings provided.
  86 The similarity percentage is the ratio of the found longest common substring
  87 against the *longer* of the two input strings.
  88 For example, given ``val`` and ``rvalue``, the similarity is `3 / 6 = 50`\%.
  89 If no characters are common in the two string, `0`\%.
  90
  91 This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
  92 The default bounds are: below `40`\% dissimilar and above `50`\% similar.
  93 This heuristic is case-insensitive.
  94
  95 Levenshtein distance (as `Levenshtein`)
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 The `Levenshtein distance <http://en.wikipedia.org/wiki/Levenshtein_distance>`_
  99 describes how many single-character changes (additions, changes, or removals)
 100 must be applied to transform one string into another.
 101
 102 The Levenshtein distance is translated into a similarity percentage by dividing
 103 it with the length of the *longer* string, and taking its complement with
 104 regards to `100`\%.
 105 For example, given ``something`` and ``anything``, the distance is `4` edits,
 106 and the similarity percentage is `100`\% `- 4 / 9 = 55.55...`\%.
 107
 108 This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
 109 The default bounds are: below `50`\% dissimilar and above `66`\% similar.
 110 This heuristic is case-sensitive.
 111
 112 Jaro--Winkler distance (as `JaroWinkler`)
 113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 The `Jaro--Winkler distance <http://en.wikipedia.org/wiki/Jaro–Winkler_distance>`_
 116 is an edit distance like the Levenshtein distance.
 117 It is calculated from the amount of common characters that are sufficiently
 118 close to each other in position, and to-be-changed characters.
 119 The original definition of Jaro has been extended by Winkler to weigh prefix
 120 similarities more.
 121 The similarity percentage is expressed as an average of the common and
 122 non-common characters against the length of both strings.
 123
 124 This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
 125 The default bounds are: below `75`\% dissimilar and above `85`\% similar.
 126 This heuristic is case-insensitive.
 127
 128 Sørensen--Dice coefficient (as `Dice`)
 129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 130
 131 The `Sørensen--Dice coefficient <http://en.wikipedia.org/wiki/Sørensen–Dice_coefficient>`_
 132 was originally defined to measure the similarity of two sets.
 133 Formally, the coefficient is calculated by dividing `2 * #(intersection)` with
 134 `#(set1) + #(set2)`, where `#()` is the cardinality function of sets.
 135 This metric is applied to strings by creating bigrams (substring sequences of
 136 length 2) of the two strings and using the set of bigrams for the two strings
 137 as the two sets.
 138
 139 This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
 140 The default bounds are: below `60`\% dissimilar and above `70`\% similar.
 141 This heuristic is case-insensitive.
 142
 143
 144 Options
 145 -------
 146
 147 .. option:: MinimumIdentifierNameLength
 148
 149     Sets the minimum required length the argument and parameter names
 150     need to have. Names shorter than this length will be ignored.
 151     Defaults to `3`.
 152
 153 .. _opt_Abbreviations:
 154
 155 .. option:: Abbreviations
 156
 157     For the **Abbreviation** heuristic
 158     (:ref:`see here<abbreviation_heuristic>`), this option configures the
 159     abbreviations in the `"abbreviation=abbreviated_value"` format.
 160     The option is a string, with each value joined by `";"`.
 161
 162     By default, the following abbreviations are set:
 163
 164        * `addr=address`
 165        * `arr=array`
 166        * `attr=attribute`
 167        * `buf=buffer`
 168        * `cl=client`
 169        * `cnt=count`
 170        * `col=column`
 171        * `cpy=copy`
 172        * `dest=destination`
 173        * `dist=distance`
 174        * `dst=distance`
 175        * `elem=element`
 176        * `hght=height`
 177        * `i=index`
 178        * `idx=index`
 179        * `len=length`
 180        * `ln=line`
 181        * `lst=list`
 182        * `nr=number`
 183        * `num=number`
 184        * `pos=position`
 185        * `ptr=pointer`
 186        * `ref=reference`
 187        * `src=source`
 188        * `srv=server`
 189        * `stmt=statement`
 190        * `str=string`
 191        * `val=value`
 192        * `var=variable`
 193        * `vec=vector`
 194        * `wdth=width`
 195
 196 The configuration options for each implemented heuristic (see above) is
 197 constructed dynamically.
 198 In the following, `<HeuristicName>` refers to one of the keys from the
 199 heuristics implemented.
 200
 201 .. option:: <HeuristicName>
 202
 203     `True` or `False`, whether a particular heuristic, such as `Equality` or
 204     `Levenshtein` is enabled.
 205
 206     Defaults to `True` for every heuristic.
 207
 208 .. _opt_Bounds:
 209
 210 .. option:: <HeuristicName>DissimilarBelow, <HeuristicName>SimilarAbove
 211
 212     A value between `0` and `100`, expressing a percentage.
 213     The bounds set what percentage of similarity the heuristic must deduce
 214     for the two identifiers to be considered similar or dissimilar by the
 215     check.
 216
 217     Given arguments ``arg1`` and ``arg2`` passed to ``param1`` and ``param2``,
 218     respectively, the bounds check is performed in the following way:
 219     If the similarity of the currently passed argument order
 220     (``arg1`` to ``param1``) is **below** the `DissimilarBelow` threshold, and
 221     the similarity of the suggested swapped order (``arg1`` to ``param2``) is
 222     **above** the `SimilarAbove` threshold, the swap is reported.
 223
 224     For the defaults of each heuristic, :ref:`see above<heuristics>`.
 225
 226
 227 Name synthesis
 228 --------------
 229
 230 When comparing the argument names and parameter names, the following logic is
 231 used to gather the names for comparison:
 232
 233 Parameter names are the identifiers as written in the source code.
 234
 235 Argument names are:
 236
 237   * If a variable is passed, the variable's name.
 238   * If a subsequent function call's return value is used as argument, the called
 239     function's name.
 240   * Otherwise, empty string.
 241
 242 Empty argument or parameter names are ignored by the heuristics.