1.. title:: clang-tidy - readability-suspicious-call-argument 2 3readability-suspicious-call-argument 4==================================== 5 6Finds function calls where the arguments passed are provided out of order, 7based on the difference between the argument name and the parameter names 8of the function. 9 10Given 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) 13than ``tvar`` (the parameter it is currently passed to) **and** ``bar`` is 14more similar to ``tvar`` than ``uvar``. 15 16Warnings might indicate either that the arguments are swapped, or that the 17names' cross-similarity might hinder code comprehension. 18 19.. _heuristics: 20 21Heuristics 22---------- 23 24The following heuristics are implemented in the check. 25If **any** of the enabled heuristics deem the arguments to be provided out of 26order, a warning will be issued. 27 28The heuristics themselves are implemented by considering pairs of strings, and 29are symmetric, so in the following there is no distinction on which string is 30the argument name and which string is the parameter name. 31 32Equality 33^^^^^^^^ 34 35The most trivial heuristic, which compares the two strings for case-insensitive 36equality. 37 38.. _abbreviation_heuristic: 39 40Abbreviation 41^^^^^^^^^^^^ 42 43Common abbreviations can be specified which will deem the strings similar if 44the abbreviated and the abbreviation stand together. 45For example, if ``src`` is registered as an abbreviation for ``source``, then 46the 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 54The abbreviations to recognise can be configured with the 55:ref:`Abbreviations<opt_Abbreviations>` check option. 56This heuristic is case-insensitive. 57 58Prefix 59^^^^^^ 60 61The *prefix* heuristic reports if one of the strings is a sufficiently long 62prefix of the other string, e.g. ``target`` to ``targetPtr``. 63The similarity percentage is the length ratio of the prefix to the longer 64string, in the previous example, it would be `6 / 9 = 66.66...`\%. 65 66This heuristic can be configured with :ref:`bounds<opt_Bounds>`. 67The default bounds are: below `25`\% dissimilar and above `30`\% similar. 68This heuristic is case-insensitive. 69 70Suffix 71^^^^^^ 72 73Analogous to the `Prefix` heuristic. 74In the case of ``oldValue`` and ``value`` compared, the similarity percentage 75is `8 / 5 = 62.5`\%. 76 77This heuristic can be configured with :ref:`bounds<opt_Bounds>`. 78The default bounds are: below `25`\% dissimilar and above `30`\% similar. 79This heuristic is case-insensitive. 80 81Substring 82^^^^^^^^^ 83 84The substring heuristic combines the prefix and the suffix heuristic, and tries 85to find the *longest common substring* in the two strings provided. 86The similarity percentage is the ratio of the found longest common substring 87against the *longer* of the two input strings. 88For example, given ``val`` and ``rvalue``, the similarity is `3 / 6 = 50`\%. 89If no characters are common in the two string, `0`\%. 90 91This heuristic can be configured with :ref:`bounds<opt_Bounds>`. 92The default bounds are: below `40`\% dissimilar and above `50`\% similar. 93This heuristic is case-insensitive. 94 95Levenshtein distance (as `Levenshtein`) 96^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97 98The `Levenshtein distance <http://en.wikipedia.org/wiki/Levenshtein_distance>`_ 99describes how many single-character changes (additions, changes, or removals) 100must be applied to transform one string into another. 101 102The Levenshtein distance is translated into a similarity percentage by dividing 103it with the length of the *longer* string, and taking its complement with 104regards to `100`\%. 105For example, given ``something`` and ``anything``, the distance is `4` edits, 106and the similarity percentage is `100`\% `- 4 / 9 = 55.55...`\%. 107 108This heuristic can be configured with :ref:`bounds<opt_Bounds>`. 109The default bounds are: below `50`\% dissimilar and above `66`\% similar. 110This heuristic is case-sensitive. 111 112Jaro--Winkler distance (as `JaroWinkler`) 113^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 114 115The `Jaro--Winkler distance <http://en.wikipedia.org/wiki/Jaro–Winkler_distance>`_ 116is an edit distance like the Levenshtein distance. 117It is calculated from the amount of common characters that are sufficiently 118close to each other in position, and to-be-changed characters. 119The original definition of Jaro has been extended by Winkler to weigh prefix 120similarities more. 121The similarity percentage is expressed as an average of the common and 122non-common characters against the length of both strings. 123 124This heuristic can be configured with :ref:`bounds<opt_Bounds>`. 125The default bounds are: below `75`\% dissimilar and above `85`\% similar. 126This heuristic is case-insensitive. 127 128Sørensen--Dice coefficient (as `Dice`) 129^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 130 131The `Sørensen--Dice coefficient <http://en.wikipedia.org/wiki/Sørensen–Dice_coefficient>`_ 132was originally defined to measure the similarity of two sets. 133Formally, the coefficient is calculated by dividing `2 * #(intersection)` with 134`#(set1) + #(set2)`, where `#()` is the cardinality function of sets. 135This metric is applied to strings by creating bigrams (substring sequences of 136length 2) of the two strings and using the set of bigrams for the two strings 137as the two sets. 138 139This heuristic can be configured with :ref:`bounds<opt_Bounds>`. 140The default bounds are: below `60`\% dissimilar and above `70`\% similar. 141This heuristic is case-insensitive. 142 143 144Options 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 196The configuration options for each implemented heuristic (see above) is 197constructed dynamically. 198In the following, `<HeuristicName>` refers to one of the keys from the 199heuristics 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 227Name synthesis 228-------------- 229 230When comparing the argument names and parameter names, the following logic is 231used to gather the names for comparison: 232 233Parameter names are the identifiers as written in the source code. 234 235Argument 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 242Empty argument or parameter names are ignored by the heuristics. 243