Clearly articulate the rule for public methods parameter names in section 5.2.6 of Google Java Style Guide
- Dominant language
- HTML
- Stars
- 39.6k
- Forks
- 12.9k
- Avg merge
- 42m
- Merged PRs (30d)
- 15
Description
[Section 5.2.6](https://google.github.io/styleguide/javaguide.html#s5.2.6-parameter-names) of Google Java Style Guide contains the following sentence:
> One-character parameter names in public methods should be avoided.
This formulation is not strict enough. What does ```should be avoided``` mean?
- forbidden ?
- discouraged ?
- allowed but it is better not to do this?
It does not clearly say whether one-character parameter names in public methods are allowed or must not be used. As a result the following problems and discussions occurred: https://github.com/google/styleguide/issues/214#issuecomment-271192909 , https://github.com/google/styleguide/issues/214#issuecomment-271221185 , https://github.com/google/guava/issues/1891#issuecomment-63231281, https://github.com/checkstyle/checkstyle/pull/3774#discussion_r99048634 . It confuses people who want to use Google Java Style Guide in their teams (development process).
Please, consider using one of these formulation:
1) One-character parameter names in public methods are not allowed.
2) One-character parameter names in public methods must not be used.
3) One-character parameter names in public methods are allowed but discouraged.
4) Consider deleting the statement.
If I were to chose I would opt for the third option as it was suggested by @kevinb9n in his comment https://github.com/google/guava/issues/1891#issuecomment-63231281:
> ParameterName
This is one of the "should be avoided" guidelines in the style guide that is not treated as a bona fide rule. In fact, I don't think anyone ever really intended it to apply to non-public methods in the first place. While I imagine there are a few parameter names in here that really should be improved, I think that checkstyle should stop warning on single-character names. (And I'll try to get the guide fixed.)
Contributor guide
Assessment
This issue has not been assessed yet.