From 9c7a653fe5f354f68dadb4fa9331b9f4cd19cba6 Mon Sep 17 00:00:00 2001 From: Frank Robijn Date: Sat, 20 Jul 2024 13:26:43 +0200 Subject: [PATCH 1/5] EditorConfig file added and documented --- content/contributing/cs-coding-style.md | 93 +++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/content/contributing/cs-coding-style.md b/content/contributing/cs-coding-style.md index 6c5419e8c..b251a75bd 100644 --- a/content/contributing/cs-coding-style.md +++ b/content/contributing/cs-coding-style.md @@ -34,6 +34,99 @@ The general rule we follow is "use Visual Studio defaults". For details check th We have provided a Visual Studio 2013 vssettings file `nnnnn.vssettings` at the root of each repository, enabling C# auto-formatting conforming to the above guidelines. Note that rules 7 and 8 are not covered by the vssettings, since these are not rules currently supported by VS formatting. +A more modern way to enforce the coding style is via an `.editorconfig` file at the top of the repository: +``` +# This is a top-most .editorconfig file +root = true + +#===================================================== +# +# Settings for all file types +# +#===================================================== +[*] + +# Generic EditorConfig settings +indent_style = space +indent_size = 4 +end_of_line = crlf +charset = utf-8-bom +trim_trailing_whitespace = true +insert_final_newline = true + +# Visual Studio spell checker +spelling_languages = en-us +spelling_checkable_types = strings,identifiers,comments +spelling_error_severity = hint +spelling_exclusion_path = spelling_exclusion.dic + +#===================================================== +# +# Formatting rules for C# +# +#===================================================== +[*.cs] +dotnet_sort_system_directives_first = false +dotnet_separate_import_directive_groups = false + +# Formatting rules +csharp_new_line_before_open_brace = all +csharp_new_line_before_else = true +csharp_new_line_before_catch = true +csharp_new_line_before_finally = true +csharp_new_line_before_members_in_object_initializers = true +csharp_new_line_before_members_in_anonymous_types = true +csharp_new_line_between_query_expression_clauses = true + +csharp_indent_case_contents = true +csharp_indent_switch_labels = true +csharp_indent_labels = one_less_than_current +csharp_indent_block_contents = true +csharp_indent_braces = false +csharp_indent_case_contents_when_block = true + +csharp_space_after_cast = false +csharp_space_after_keywords_in_control_flow_statements = true +csharp_space_between_parentheses = false +csharp_space_before_colon_in_inheritance_clause = true +csharp_space_after_colon_in_inheritance_clause = true +csharp_space_around_binary_operators = before_and_after +csharp_space_between_method_declaration_parameter_list_parentheses = false +csharp_space_between_method_declaration_empty_parameter_list_parentheses = false +csharp_space_between_method_declaration_name_and_open_parenthesis = false +csharp_space_between_method_call_parameter_list_parentheses = false +csharp_space_between_method_call_empty_parameter_list_parentheses = false +csharp_space_between_method_call_name_and_opening_parenthesis = false +csharp_space_after_comma = true +csharp_space_before_comma = false +csharp_space_after_dot = false +csharp_space_before_dot = false +csharp_space_after_semicolon_in_for_statement = true +csharp_space_before_semicolon_in_for_statement = false +csharp_space_around_declaration_statements = false +csharp_space_before_open_square_brackets = false +csharp_space_between_empty_square_brackets = false +csharp_space_between_square_brackets = false + +csharp_preserve_single_line_statements = true +csharp_preserve_single_line_blocks = true + +# Naming rules + +# nF_InternalPrivateFields: all private or internal fields +dotnet_naming_symbols.nF_InternalPrivateFields.applicable_kinds = field +dotnet_naming_symbols.nF_InternalPrivateFields.applicable_accessibilities = internal, private + +# nF_CamelCaseAndUnderscore: camel casing rule +dotnet_naming_style.nF_CamelCase.capitalization = camel_case +dotnet_naming_style.nF_CamelCase.required_prefix = _ + +# nF naming rule for private or internal fields +dotnet_naming_rule.nF_InternalPrivateFields_Rule.symbols = nF_InternalPrivateFields +dotnet_naming_rule.nF_InternalPrivateFields_Rule.style = nF_CamelCaseAndUnderscore +dotnet_naming_rule.nF_InternalPrivateFields_Rule.severity = warning +``` + ## Example File ``ObservableLinkedList`1.cs:`` From 2c6bc4610c24cec1360b5c3859fc475b203ca914 Mon Sep 17 00:00:00 2001 From: Frank Robijn Date: Fri, 26 Jul 2024 11:31:33 +0200 Subject: [PATCH 2/5] EditorConfig and spell checker added and documented --- .editorconfig | 25 +++++++ content/contributing/cs-coding-style.md | 97 +------------------------ spelling_exclusion.dic | 3 + 3 files changed, 31 insertions(+), 94 deletions(-) create mode 100644 .editorconfig create mode 100644 spelling_exclusion.dic diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..5e84027e0 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,25 @@ +# EditorConfig for Visual Studio 2022: https://learn.microsoft.com/en-us/visualstudio/ide/create-portable-custom-editor-options?view=vs-2022 + +# This is a top-most .editorconfig file +root = true + +#===================================================== +# +# Settings for all file types +# +#===================================================== +[*] + +# Generic EditorConfig settings +indent_style = space +indent_size = 4 +end_of_line = crlf +charset = utf-8-bom +trim_trailing_whitespace = true +insert_final_newline = true + +# Visual Studio spell checker +spelling_languages = en-us +spelling_checkable_types = strings,identifiers,comments +spelling_error_severity = information +spelling_exclusion_path = spelling_exclusion.dic diff --git a/content/contributing/cs-coding-style.md b/content/contributing/cs-coding-style.md index b251a75bd..65b0a08a9 100644 --- a/content/contributing/cs-coding-style.md +++ b/content/contributing/cs-coding-style.md @@ -1,4 +1,4 @@ -# C# Coding Style +# C# Coding Style For non code files (xml etc) our current best guidance is consistency. When editing files, keep new code and changes consistent with the style in the files. For new files, it should conform to the style for that component. Last, if there's a completely new component, anything that is reasonably broadly accepted is fine. @@ -32,100 +32,9 @@ The general rule we follow is "use Visual Studio defaults". For details check th 18. Don't forget the header, the 2 lines simplified version can be used. 19. Try to avoid abbreviation, always use longer names when possible and where it does make sense. It is acceptable for very known ones to use them like HTTP for example. Also, if using abbreviations, the names should follow the the pattern. For example, if you are using `HTTP` in a name of a function called `Something`, it will then be `HttpSomething`. This goes as well for namespaces, classes, properties, variable names. -We have provided a Visual Studio 2013 vssettings file `nnnnn.vssettings` at the root of each repository, enabling C# auto-formatting conforming to the above guidelines. Note that rules 7 and 8 are not covered by the vssettings, since these are not rules currently supported by VS formatting. +We have provided an EditorConfig file `.editorconfig` at the root of each repository, enabling C# auto-formatting conforming to the above guidelines, in particular rules 1, 2 and 9. Visual Studio cannot auto-correct code to comply with other rules; these are verified by StyleCop when the code is compiled. -A more modern way to enforce the coding style is via an `.editorconfig` file at the top of the repository: -``` -# This is a top-most .editorconfig file -root = true - -#===================================================== -# -# Settings for all file types -# -#===================================================== -[*] - -# Generic EditorConfig settings -indent_style = space -indent_size = 4 -end_of_line = crlf -charset = utf-8-bom -trim_trailing_whitespace = true -insert_final_newline = true - -# Visual Studio spell checker -spelling_languages = en-us -spelling_checkable_types = strings,identifiers,comments -spelling_error_severity = hint -spelling_exclusion_path = spelling_exclusion.dic - -#===================================================== -# -# Formatting rules for C# -# -#===================================================== -[*.cs] -dotnet_sort_system_directives_first = false -dotnet_separate_import_directive_groups = false - -# Formatting rules -csharp_new_line_before_open_brace = all -csharp_new_line_before_else = true -csharp_new_line_before_catch = true -csharp_new_line_before_finally = true -csharp_new_line_before_members_in_object_initializers = true -csharp_new_line_before_members_in_anonymous_types = true -csharp_new_line_between_query_expression_clauses = true - -csharp_indent_case_contents = true -csharp_indent_switch_labels = true -csharp_indent_labels = one_less_than_current -csharp_indent_block_contents = true -csharp_indent_braces = false -csharp_indent_case_contents_when_block = true - -csharp_space_after_cast = false -csharp_space_after_keywords_in_control_flow_statements = true -csharp_space_between_parentheses = false -csharp_space_before_colon_in_inheritance_clause = true -csharp_space_after_colon_in_inheritance_clause = true -csharp_space_around_binary_operators = before_and_after -csharp_space_between_method_declaration_parameter_list_parentheses = false -csharp_space_between_method_declaration_empty_parameter_list_parentheses = false -csharp_space_between_method_declaration_name_and_open_parenthesis = false -csharp_space_between_method_call_parameter_list_parentheses = false -csharp_space_between_method_call_empty_parameter_list_parentheses = false -csharp_space_between_method_call_name_and_opening_parenthesis = false -csharp_space_after_comma = true -csharp_space_before_comma = false -csharp_space_after_dot = false -csharp_space_before_dot = false -csharp_space_after_semicolon_in_for_statement = true -csharp_space_before_semicolon_in_for_statement = false -csharp_space_around_declaration_statements = false -csharp_space_before_open_square_brackets = false -csharp_space_between_empty_square_brackets = false -csharp_space_between_square_brackets = false - -csharp_preserve_single_line_statements = true -csharp_preserve_single_line_blocks = true - -# Naming rules - -# nF_InternalPrivateFields: all private or internal fields -dotnet_naming_symbols.nF_InternalPrivateFields.applicable_kinds = field -dotnet_naming_symbols.nF_InternalPrivateFields.applicable_accessibilities = internal, private - -# nF_CamelCaseAndUnderscore: camel casing rule -dotnet_naming_style.nF_CamelCase.capitalization = camel_case -dotnet_naming_style.nF_CamelCase.required_prefix = _ - -# nF naming rule for private or internal fields -dotnet_naming_rule.nF_InternalPrivateFields_Rule.symbols = nF_InternalPrivateFields -dotnet_naming_rule.nF_InternalPrivateFields_Rule.style = nF_CamelCaseAndUnderscore -dotnet_naming_rule.nF_InternalPrivateFields_Rule.severity = warning -``` +The EditorConfig also configures the Visual Studio spell checker. The spell checker is not enabled by default; it can be turned on/off by a button on the toolbar (the button with text *abc* and a green checkmark) or via the menu *Edit | Advanced | Toggle Spell Checker*. At the moment it can analyse the C#, C++ and markdown files that are open in he IDE. Code files typically contain jargon that is not recognised, e.g., the name of a communication protocol. If the spell checker flags such a word, choose to ignore it. The word will be added to the `spelling_exclusion.dic` file at the root of the repository. ## Example File diff --git a/spelling_exclusion.dic b/spelling_exclusion.dic new file mode 100644 index 000000000..887b5fd1c --- /dev/null +++ b/spelling_exclusion.dic @@ -0,0 +1,3 @@ +nano +intellisense +nanoff From 37a3188e2e0d9a629fe264141ca82a4a3ddb5bef Mon Sep 17 00:00:00 2001 From: Frank Robijn Date: Thu, 1 Aug 2024 14:00:03 +0200 Subject: [PATCH 3/5] Static fields should be prefixed with s_ (not can) --- content/contributing/cs-coding-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/contributing/cs-coding-style.md b/content/contributing/cs-coding-style.md index 65b0a08a9..2d033d6ee 100644 --- a/content/contributing/cs-coding-style.md +++ b/content/contributing/cs-coding-style.md @@ -6,7 +6,7 @@ The general rule we follow is "use Visual Studio defaults". For details check th 1. We use [Allman style](https://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. Even a single line statement block should go with braces and nested in other statement blocks that use braces. 2. We use four spaces of indentation (no tabs). -3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix static fields can be used with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (i.e. `static readonly` not `readonly static`). +3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (i.e. `static readonly` not `readonly static`). 4. We avoid `this.` unless absolutely necessary. 5. We always specify the visibility, even if it's the default (i.e. `private string _foo` not `string _foo`). Visibility should be the first modifier (i.e. From dc161b78690e45b3ca1ed07229be607642d78a10 Mon Sep 17 00:00:00 2001 From: Frank Robijn Date: Mon, 21 Oct 2024 13:55:32 +0200 Subject: [PATCH 4/5] Source of the nanoFramework .editorconfig added. --- content/contributing/cs-coding-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/contributing/cs-coding-style.md b/content/contributing/cs-coding-style.md index 2d033d6ee..b1bb786f3 100644 --- a/content/contributing/cs-coding-style.md +++ b/content/contributing/cs-coding-style.md @@ -32,7 +32,7 @@ The general rule we follow is "use Visual Studio defaults". For details check th 18. Don't forget the header, the 2 lines simplified version can be used. 19. Try to avoid abbreviation, always use longer names when possible and where it does make sense. It is acceptable for very known ones to use them like HTTP for example. Also, if using abbreviations, the names should follow the the pattern. For example, if you are using `HTTP` in a name of a function called `Something`, it will then be `HttpSomething`. This goes as well for namespaces, classes, properties, variable names. -We have provided an EditorConfig file `.editorconfig` at the root of each repository, enabling C# auto-formatting conforming to the above guidelines, in particular rules 1, 2 and 9. Visual Studio cannot auto-correct code to comply with other rules; these are verified by StyleCop when the code is compiled. +We have provided an EditorConfig file `.editorconfig` at the root of each repository that contains the code style rules. If a repository does not yet have the `.editorconfig` file, copy it from another repository, e.g., [from here](https://github.com/nanoframework/nanoFirmwareFlasher/blob/main/.editorconfig). The EditorConfig also configures the Visual Studio spell checker. The spell checker is not enabled by default; it can be turned on/off by a button on the toolbar (the button with text *abc* and a green checkmark) or via the menu *Edit | Advanced | Toggle Spell Checker*. At the moment it can analyse the C#, C++ and markdown files that are open in he IDE. Code files typically contain jargon that is not recognised, e.g., the name of a communication protocol. If the spell checker flags such a word, choose to ignore it. The word will be added to the `spelling_exclusion.dic` file at the root of the repository. From 7ca00f03dc4cd5f3adbc716726818f8db384205d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Sim=C3=B5es?= Date: Wed, 16 Apr 2025 14:43:47 +0100 Subject: [PATCH 5/5] Add mention to project editoconfig source file --- content/contributing/cs-coding-style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/contributing/cs-coding-style.md b/content/contributing/cs-coding-style.md index b1bb786f3..786cc7d59 100644 --- a/content/contributing/cs-coding-style.md +++ b/content/contributing/cs-coding-style.md @@ -32,7 +32,7 @@ The general rule we follow is "use Visual Studio defaults". For details check th 18. Don't forget the header, the 2 lines simplified version can be used. 19. Try to avoid abbreviation, always use longer names when possible and where it does make sense. It is acceptable for very known ones to use them like HTTP for example. Also, if using abbreviations, the names should follow the the pattern. For example, if you are using `HTTP` in a name of a function called `Something`, it will then be `HttpSomething`. This goes as well for namespaces, classes, properties, variable names. -We have provided an EditorConfig file `.editorconfig` at the root of each repository that contains the code style rules. If a repository does not yet have the `.editorconfig` file, copy it from another repository, e.g., [from here](https://github.com/nanoframework/nanoFirmwareFlasher/blob/main/.editorconfig). +We have provided an EditorConfig file `.editorconfig` at the root of each repository that contains the code style rules. If a repository does not yet have the `.editorconfig` file, it should be copied from the project source [here](https://github.com/nanoframework/.github/blob/main/VS%20templates%2Bconfig/.editorconfig). Which should be kept up to date. Note that there is also a spelling exclusion file along with it: spelling_exclusion.dic. The EditorConfig also configures the Visual Studio spell checker. The spell checker is not enabled by default; it can be turned on/off by a button on the toolbar (the button with text *abc* and a green checkmark) or via the menu *Edit | Advanced | Toggle Spell Checker*. At the moment it can analyse the C#, C++ and markdown files that are open in he IDE. Code files typically contain jargon that is not recognised, e.g., the name of a communication protocol. If the spell checker flags such a word, choose to ignore it. The word will be added to the `spelling_exclusion.dic` file at the root of the repository.