Visualstudio-docs: Unclear ordering of dotnet naming rules across files

[henrygab]

Background:

.editorconfig files are defined to allow overriding of values found in a common root location, by having a .editorconfig file "closer to" the source file being processed.

From https://editorconfig.org/#file-location:

EditorConfig files are read top to bottom and the most recent rules found take precedence.
Properties from matching EditorConfig sections are applied in the order they were read,
so properties in closer files take precedence.

https://editorconfig.org/#file-format-details

EditorConfig files are read top to bottom and the most recent rules found take precedence.

https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-naming-conventions

Naming conventions should be ordered from most-specific to least-specific
in the .editorconfig file. The first rule encountered that can be applied
is the only rule that is applied.

Scenario

Directory Foo has default formatting defined for private static fields as "s_NameOfField"
Directory Foo\Bar wants to further define private static readonly as "sr_NameOfField"
and also define all other private fields as "_NameOfField".

Sample C:\Foo\.editorconfig contents

dotnet_naming_symbols.private_static_field.applicable_kinds = field
dotnet_naming_symbols.private_static_field.applicable_accessibilities = private, internal, protected_internal
dotnet_naming_symbols.private_static_field.required_modifiers = static

dotnet_naming_style.private_static_field.capitalization = pascal_case
dotnet_naming_style.private_static_field.required_prefix = s_

dotnet_naming_rule.private_static_field_rule.symbols  = private_static_field
dotnet_naming_rule.private_static_field_rule.style    = private_static_field_style
dotnet_naming_rule.private_static_field_rule.severity = warning

Sample C:\Foo\Bar\.editorconfig contents

# first { static+readonly, private field }, then { private field } naming symbols
dotnet_naming_symbols.private_static_readonly_field.applicable_kinds = field
dotnet_naming_symbols.private_static_readonly_field.applicable_accessibilities = private, internal, protected_internal
dotnet_naming_symbols.private_static_readonly_field.required_modifiers = static, readonly

dotnet_naming_symbols.private_field.applicable_kinds = field
dotnet_naming_symbols.private_field.applicable_accessibilities = private, internal, protected_internal

# styles for above two items
dotnet_naming_style.private_static_readonly_field_style.capitalization = pascal_case
dotnet_naming_style.private_static_readonly_field_style.required_prefix = sr_

dotnet_naming_style.private_field_style.capitalization = pascal_case
dotnet_naming_style.private_field_style.required_prefix = _

# and rules
dotnet_naming_rule.private_static_readonly_field_rule.symbols  = private_static_readonly_field
dotnet_naming_rule.private_static_readonly_field_rule.style    = private_static_readonly_field_style
dotnet_naming_rule.private_static_readonly_field_rule.severity = warning

dotnet_naming_rule.private_field_rule.symbols  = private_field
dotnet_naming_rule.private_field_rule.style    = private_field_style
dotnet_naming_rule.private_field_rule.severity = warning

Sample source file C:\Foo\Bar\Baz.cs contents

using System;
namespace Foo.Bar {
    public class Baz {
        private byte _Alpha;
        private static byte s_Beta;
        private static readonly byte sr_Theta;
    };
}

If reformatting this source file...

What _should_ the result be according to the documentation?

This is what I understand based on the documentation:

1. C:\foo.editorconfig contents are processed first.
2. c:\foo\bar.editorconfig contents are processed second.
3. _Alpha matches only the private_field_rule.
   Therefore, _Alpha is left untouched.
4. s_Beta could match both private_field_rule and private_static_field_rule.
   private_static_field_rule is applied because it was read first.
   Therefore, s_Beta is left untouched.
5. sr_Theta could match all three rules.
   private_static_field_rule is once again applied because it was read first.
   Therefore, sr_Theta is reformatted to s_Theta.

If steps 1 and 2 are swapped, then it would look as follows:

1. c:\foo\bar.editorconfig contents are processed first.
2. C:\foo.editorconfig contents are processed second.
3. _Alpha matches only the private_field_rule.
   Therefore, _Alpha is left untouched.
4. s_Beta could match both private_field_rule and private_static_field_rule.
   private_field_rule is applied because it was read first.
   Therefore, s_Beta is reformatted to _Beta.
5. sr_Theta could match all three rules.
   private_static_field_rule is applied because it was read first.
   Therefore, sr_Theta is reformatted to s_Theta.

Summary

It also appears that the documentation suggests no architecturally
simple way of defining default rules in the root of a project, and
being able to overrule only portions in a subdirectory.

Is this understanding correct? Or, for the formatting rules, are all
the rules processed regardless of order, and the "most specific" rule
wins? Or, is it even more complex?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: b402d2e0-a53a-b61a-4da8-b5ee766d9301
• Version Independent ID: 612695df-5934-d967-d709-500ce02b1395
• Content: .NET Naming Conventions For EditorConfig files - Visual Studio
• Content Source: docs/ide/editorconfig-naming-conventions.md
• Product: visual-studio-dev15
• GitHub Login: @gewarren
• Microsoft Alias: gewarren

[gewarren]

@kendrahavens Do you know the answers to these precedence questions for editorconfig?

[kendrahavens]

Thanks for taking the time to file feedback! I'm not sure if a few of these questions are outdated as we developed the tooling in the past months. Sorry if that is the case and this is belated!

In the above sample the C:\Foo\Bar\ .editorconfig will override the root editorconfig settings with the editorconfig in the local Bar directory. (Unless you actually have two editorconfigs in the same directory in the sample. We do not recommend that scenario.)

no architecturally simple way of defining default rules in the root of a project

You can definitely add a .editorconfig at the root of a project/solution to define default rules and override those in subdirectories. Most commonly this file would exist in a 'Solution Items' folder on the .sln directory level.

overrule only portions in a subdirectory

For overruling portion of a subdirectory you would need to create separate folders and include a .editorconfig in each where the rules differ.

Let me know if I missed a subtlety of the question. I can take this to the product team for further design discussion if needed.

[henrygab]

Thanks for the response, @kendrahavens.
_[[ First, the lack of a slash was a weirdness with markdown headers... had to double-up the "\" before the period for some reason. I've updated the above to make the filenames in the headings clear. ]]_

I encourage you to ask the question of multiple people, to try to deduce what should happen _according to the documentation_, without actually writing the rules.

Let me try to narrow the focus:

Rules and files

C:\Foo\.editorconfig

Rule 1 matches: private static fields

C:\Foo\Bar\.editorconfig

Rule 2 matches: private fields
Rule 3 matches: private static readonly fields

If all three rules are in one file...

The rules can easily be listed in order, from most-specific to least-specific.
Rule 2 is the least specific, as it only requires the field to be private.
Rule 1 is in between, as it also requires the field to be static.
Rule 3 is the most specific, as it requires the field to be both static and readonly.

However, the order the rules are read:

Rule 2 is read first (closest file, first rule).
Rule 3 is read next (closest file, second rule).
Rule 1 is read last (parent directory file)

Documentation based descriptions of what happens

https://editorconfig.org/#file-location:

EditorConfig files are read top to bottom and the most recent rules found take precedence. Properties from matching EditorConfig sections are applied in the order they were read, so properties in closer files take precedence.

Thus, rules 2 and 3 take precedence over rule 1, because they are in the closer file ("properties in closer files take precedence"), and rule 3 takes precedence over rule 2, because it was read most recently when the .editorconfig file was finished being processed..

https://editorconfig.org/#file-format-details

EditorConfig files are read top to bottom and the most recent rules found take precedence.

This confirms that rule 3 takes precedence over rule 2, but is silent as to relative precedence as to rule 1.

https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-naming-conventions:

Naming conventions should be ordered from most-specific to least-specific
in the .editorconfig file. The first rule encountered that can be applied is the only rule that is applied.

This contradicts the above two statements, stating that "the first rule encountered that can be applied is the only rule that is applied". Thus, if true, rule 2 takes precedence over rule 3, as it would be first to be "encountered" when reading the .editorconfig file "top to bottom".

Therefore, there appears to be a contradiction in the documentation.

[sharwell]

@henrygab The rules you describe were implemented correctly for properties _with the same name_. For your example, you describe the relation between different properties with different names. The specification is ambiguous with respect to this situation, and for better or worse the naming conventions are applied in the reverse of what you described above. There is an earlier discussion regarding this behavior in dotnet/roslyn#23391. At this point, a change to the ordering would be a substantial breaking change for existing users.

[henrygab]

@sharwell Thanks for confirming the specification is ambiguous (thus my question). Bigger thanks for helping explain the current situation that occurs. Specifically, you say they are applied "in reverse of what [I] described above". I actually described a lot of things above, so I'm still unclear.

Would you mind taking an extra 15-20 minutes to describe the behavior specifically?

Thanks!

[tonyhallett]

[henrygab]

[sharwell]

[gewarren]