1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
For clarity, and to avoid potentially incorrectly swapping arguments, arguments
may be explicitly matched to their parameter by preceding them with a block
comment containing the parameter name followed by an equals sign. Mismatches
between the name in the comment and the actual name will then cause a
compilation error.
## Parameter-name comment style
The style accepted for comments that name parameters is to use a block comment,
before the argument, including an equals sign.
```java
test(/* param1= */ arg1,
/* param2= */ arg2);
```
The use of spaces (or not) around the parameter name and the equals sign is
optional.
### Rationale
There are a variety of styles in use for commenting arguments in method calls.
Adopting a consistent style should be valuable for readability. There are also a
variety of shortcomings with alternative techniques.
*Shortcomings with the use of line comments* (instead of block comments).
Firstly, they force a vertical layout of the method call even if it would fit on
one line. Secondly, associating line comments with arguments is hard to get
right. For example:
```java
test(arg1, // param1
arg2); // param2
```
In this example `param1` is in the same parse tree node as `arg2` (because its
after the comma) and `param2` is not even in the same parse tree node as the
method invocation (its after the semi-colon).
*Shortcomings with the use of block comments after the argument* arise because
its not always natural to put them in the right place. For example:
```java
// not as intended
test(arg1, /* param1 */
arg2); /* param2 */
// intended
test(arg1 /* param1 */,
arg2 /* param2 */);
```
*The benefit of including the equals-sign* is that it helps associate the
comment with the correct argument. For example:
```java
test(arg1, /* param2= */
arg2);
```
In this example the formatter has moved the comment that should be before `arg2`
onto the previous line. However, the inclusion of the equals sign means that
there is at least a visual cue that this has happened.
*Commonality with other languages*. Python support for named parameters uses an
equals sign, and the clang-tidy
[bugprone-argument-comment](https://clang.llvm.org/extra/clang-tidy/checks/bugprone-argument-comment.html)
check uses block-comments with equals signs.
|
