google / google/styleguide

Clearly articulate the rule for public methods parameter names in section 5.2.6 of Google Java Style Guide

Open
#226 0 comments 0 reactions 0 assignees View on GitHub
lang:java
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.