243 lines · plain
1.. title:: clang-tidy - readability-suspicious-call-argument2 3readability-suspicious-call-argument4====================================5 6Finds function calls where the arguments passed are provided out of order,7based on the difference between the argument name and the parameter names8of the function.9 10Given a function call ``f(foo, bar);`` and a function signature11``void f(T tvar, U uvar)``, the arguments ``foo`` and ``bar`` are swapped if12``foo`` (the argument name) is more similar to ``uvar`` (the other parameter)13than ``tvar`` (the parameter it is currently passed to) **and** ``bar`` is14more similar to ``tvar`` than ``uvar``.15 16Warnings might indicate either that the arguments are swapped, or that the17names' cross-similarity might hinder code comprehension.18 19.. _heuristics:20 21Heuristics22----------23 24The following heuristics are implemented in the check.25If **any** of the enabled heuristics deem the arguments to be provided out of26order, a warning will be issued.27 28The heuristics themselves are implemented by considering pairs of strings, and29are symmetric, so in the following there is no distinction on which string is30the argument name and which string is the parameter name.31 32Equality33^^^^^^^^34 35The most trivial heuristic, which compares the two strings for case-insensitive36equality.37 38.. _abbreviation_heuristic:39 40Abbreviation41^^^^^^^^^^^^42 43Common abbreviations can be specified which will deem the strings similar if44the abbreviated and the abbreviation stand together.45For example, if ``src`` is registered as an abbreviation for ``source``, then46the 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 the55:ref:`Abbreviations<opt_Abbreviations>` check option.56This heuristic is case-insensitive.57 58Prefix59^^^^^^60 61The *prefix* heuristic reports if one of the strings is a sufficiently long62prefix of the other string, e.g. ``target`` to ``targetPtr``.63The similarity percentage is the length ratio of the prefix to the longer64string, 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 70Suffix71^^^^^^72 73Analogous to the `Prefix` heuristic.74In the case of ``oldValue`` and ``value`` compared, the similarity percentage75is `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 81Substring82^^^^^^^^^83 84The substring heuristic combines the prefix and the suffix heuristic, and tries85to find the *longest common substring* in the two strings provided.86The similarity percentage is the ratio of the found longest common substring87against 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 dividing103it with the length of the *longer* string, and taking its complement with104regards 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 sufficiently118close to each other in position, and to-be-changed characters.119The original definition of Jaro has been extended by Winkler to weigh prefix120similarities more.121The similarity percentage is expressed as an average of the common and122non-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)` with134`#(set1) + #(set2)`, where `#()` is the cardinality function of sets.135This metric is applied to strings by creating bigrams (substring sequences of136length 2) of the two strings and using the set of bigrams for the two strings137as 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 144Options145-------146 147.. option:: MinimumIdentifierNameLength148 149 Sets the minimum required length the argument and parameter names150 need to have. Names shorter than this length will be ignored.151 Defaults to `3`.152 153.. _opt_Abbreviations:154 155.. option:: Abbreviations156 157 For the **Abbreviation** heuristic158 (:ref:`see here<abbreviation_heuristic>`), this option configures the159 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) is197constructed dynamically.198In the following, `<HeuristicName>` refers to one of the keys from the199heuristics implemented.200 201.. option:: <HeuristicName>202 203 `True` or `False`, whether a particular heuristic, such as `Equality` or204 `Levenshtein` is enabled.205 206 Defaults to `True` for every heuristic.207 208.. _opt_Bounds:209 210.. option:: <HeuristicName>DissimilarBelow, <HeuristicName>SimilarAbove211 212 A value between `0` and `100`, expressing a percentage.213 The bounds set what percentage of similarity the heuristic must deduce214 for the two identifiers to be considered similar or dissimilar by the215 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 order220 (``arg1`` to ``param1``) is **below** the `DissimilarBelow` threshold, and221 the similarity of the suggested swapped order (``arg1`` to ``param2``) is222 **above** the `SimilarAbove` threshold, the swap is reported.223 224 For the defaults of each heuristic, :ref:`see above<heuristics>`.225 226 227Name synthesis228--------------229 230When comparing the argument names and parameter names, the following logic is231used 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, the239 called function's name.240 * Otherwise, empty string.241 242Empty argument or parameter names are ignored by the heuristics.243