docs icon indicating copy to clipboard operation
docs copied to clipboard

Ambiguous descriptions for option value `false` in code style options for language rules: "Do not prefer"

Open jtmedley opened this issue 1 year ago • 0 comments

Describe the issue or suggestion

For many rule options, the option value false often disables the rule. For other rule options, false keeps the rule enabled and specifies a setting for the rule that is different from that of true (as well as any other option values if present).

If an option value like false disables the rule, the documentation should say so. Many descriptions in the documentation do, but many others are ambiguous. The most common ambiguity I have seen is where true has the description "Prefer to use..." and false has the description "Do not prefer...". Will the rule be disabled in this case?

I can see at least IDE0040, IDE0042, IDE0071, IDE0075, and IDE0090 all use "Do not prefer", and that phrase is only one example of this ambiguity for false option value descriptions. It's also used here in the language rules documentation.

The examples for the option value given in these cases actually make this kind of ambiguity worse. Examples shouldn't just show code - what is being configured is the behavior of the analyzer. Here's one example with IDE0090:

true has the description "Prefer target-typed new expressions when created type is apparent" false has the description "Do not prefer target-typed new expressions"

// csharp_style_implicit_object_creation_when_type_is_apparent = true
C c = new();
C c2 = new() { Field = 0 };

// csharp_style_implicit_object_creation_when_type_is_apparent = false
C c = new C();
C c2 = new C() { Field = 0 };

This kind of example doesn't show what the option does to the analyzer's enforcement of the rule at all. When the option is set to false, will the analyzer flag code that is not styled this way, perhaps suggesting a fix to format it to match the style in the example? Or is it saying that the example code wouldn't be flagged by the analyzer?

If this is documenting an example of code that wouldn't be flagged by the analyzer, is that because the example code is in the style expected by the analyzer, or because the analyzer isn't checking this style rule at all? The example doesn't say, and the option value description doesn't make it clear. Also, every example is given this way, regardless of whether a false option value disables the rule or specifies a setting for it.

(Somewhat related to #38778 and #22450 )

jtmedley avatar Sep 04 '24 21:09 jtmedley