Style Guide Proposal: Add /* paramName= */

[Andrew Grieve]

There are a few ways to add parameter comments, but only one way that comes with correctness checking from Errorprone. 

I propose adding a note about this to the style guide, as well as a PRESUBMIT check to call out the correct style.

Proposed change: https://chromium-review.googlesource.com/c/chromium/src/+/4936726

Please let me know if you have any objections / alternatives to consider. 

[Nate Fischer]

Strong +1. I've been wanting to suggest the same, but I just didn't get around to writing a proposal.

When I was looking into this, I came across the "ParameterComment" errorprone rule, which I believe could be useful. This enforces that contributors use the `/* foo= */ value` style of comment, as opposed to the comment styles that are incompatible with the errorprone check. This is not to be confused with the ParameterName rule we already enabled, which is the rule that emits an error if the comment mismatches with the actual parameter name.

Nate Fischer | Software Engineer | ntf...@google.com

--
You received this message because you are subscribed to the Google Groups "java" group.
To unsubscribe from this group and stop receiving emails from it, send an email to java+uns...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/java/CABiQX1UQjFJz2_qdBmvJbbvA%2BZ_im6Ee1czSzu4g3r5gty6rNg%40mail.gmail.com.

[Andrew Grieve]

Neat! I didn't know about the ParameterName check. I think it's likely not useful to us currently though since we have no way to ignore existing violations (e.g. no "baseline suppressions" like lint has).

[Ted Choc]

+1 -- Seems reasonable.

- Ted

On Mon, Oct 16, 2023 at 11:52 AM 'Andrew Grieve' via java <ja...@chromium.org> wrote:

--

[Andrew Grieve]

Thanks! Going ahead with the CL then.