Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update coding guidelines #36428

Merged
merged 9 commits into from
Jul 31, 2023
Merged

Conversation

BillWagner
Copy link
Member

@BillWagner BillWagner commented Jul 27, 2023

There are a number of issues related to our coding standards used in .NET docs.

Many of the issues arise because readers conflate our style with Microsoft recommended style. The first commits made that distinction much more clear.

This may be easier to review commit-by-commit:

  1. Rearrange the content. Some naming conventions were used in both files, clearly separate them. Rearrange the order.
  2. Rework the content. Make it clear that these are our team guidelines. Point to the source for the runtime and roslyn repos. Add appropriate disclaimers that readers should feel free to modify the guidelines to suit their team's needs. Finally, add a section to explain the tools where readers can use editorconfig or analyzers to enforce the rules they want.
  3. Fix issues related to var:
  4. Fix issues related to naming conventions:
  5. Fixes #31951 : Rewrite the exception example so that it's still obvious what can fail, but couldn't be easily anticipated before making the computation.
  6. Fixes Consider moving generic type parameter naming guidelines to general C# coding conventions #30897: Move the Generic type parameter naming conventions to the general naming conventions.
  7. Fix build issues.

Internal previews

📄 File 🔗 Preview link
docs/csharp/fundamentals/coding-style/coding-conventions.md Common C# Coding Conventions
docs/csharp/fundamentals/coding-style/identifier-names.md "C# identifier names"
docs/csharp/programming-guide/generics/generic-type-parameters.md Generic type parameters (C# Programming Guide)

Make the new content organization follow better ordering.
Rewrite to match the docs team's accepted style.
Fixes dotnet#26787: clarify "obvious"
Fixes dotnet#32633: add explanation, update variable names.
Fixes dotnet#34940: Explain that `var` is preferred in LINQ queries, despite other rules.
Fixes dotnet#30626: Clarify (again) that these are our guidelines, not yours. Point out that it's not the VS default, but a configuration option.
Fixes dotnet#30642: Again, our style.
Fixes dotnet#30799: Change constant style from ALL_CAPS to PascalCase to match runtime repo.
Fixes dotnet#33959: Update variable names so delegate types are PascalCased and instances of a delegate are camelCase. Add clarifying text for the same.
Fixes dotnet#31951 : Rewrite the exception example so that it's still obvious what can fail, but couldn't be easily anticipated before making the computation.
Move the Generic type parameter naming conventions to the general naming conventions.
@BillWagner BillWagner marked this pull request as ready for review July 27, 2023 21:35
The use of `_` and `s_` follow the runtime conventions. I'd missed that in the previous commit.
Copy link
Member

@IEvangelist IEvangelist left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few nits, otherwise this looks great!

Co-authored-by: David Pine <david.pine@microsoft.com>
@IEvangelist IEvangelist merged commit 49d553f into dotnet:main Jul 31, 2023
7 checks passed
@BillWagner BillWagner deleted the coding-with-style branch July 31, 2023 13:41
BillWagner added a commit to BillWagner/docs that referenced this pull request Jul 31, 2023
See dotnet#36428 (comment)

For the issue involved, it's a better fix to create local variables for the Func and Action objects. That shows readers the distinction between the delegate type and the instance.
BillWagner added a commit that referenced this pull request Jul 31, 2023
See #36428 (comment)

For the issue involved, it's a better fix to create local variables for the Func and Action objects. That shows readers the distinction between the delegate type and the instance.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment