Debian Codegraph @

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

raw
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.