Skip to content

Post merge review and customer feedback #24237

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
May 14, 2021
Merged

Post merge review and customer feedback #24237

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ae1edcf
Address Genevieve's post merge review comments.
IEvangelist May 14, 2021
2e4efaa
Directly address customer feedback
IEvangelist May 14, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions docs/csharp/programming-guide/inside-a-program/coding-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "C# Coding Conventions - C# Programming Guide"
description: Learn about coding conventions in C#. Coding conventions create a consistent look to the code and facilitate copying, changing, and maintaining the code.
ms.date: 05/05/2021
ms.date: 05/14/2021
helpviewer_keywords:
- "coding conventions, C#"
- "Visual C#, coding conventions"
Expand All @@ -19,15 +19,16 @@ Coding conventions serve the following purposes:
> - They facilitate copying, changing, and maintaining the code.
> - They demonstrate C# best practices.

The guidelines in this article are used by Microsoft to develop samples and documentation.
> [!IMPORTANT]
> The guidelines in this article are used by Microsoft to develop samples and documentation. They were adopted from the [.NET Runtime, C# Coding Style](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/coding-style.md) guidelines. You can use them, or adapt them to your needs. The primary objectives are consistency and readability within your project, team, organization, or company source code.
Copy link

Choose a reason for hiding this comment

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

The guidelines in this article are used by Microsoft to develop samples and documentation

Hmm,... even the very basic example code in C# reference docs does not follow the newly added convention s_. It's not so popular outside runtime repo.
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/static#example---static-initialization

I think it's too late to add these new guidelines after 20 years have passed since C# was born.

Copy link

Choose a reason for hiding this comment

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

Consistency in official docs is so important. It needs a lot of work to correct these examples. Is it really worth to change at this time?

Copy link
Member Author

Choose a reason for hiding this comment

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

Hi @SIkebe,

It's never too late to update guidelines. It is natural for them to morph over time - especially with a language that continues to evolve. Following the .NET runtime as a basis is a solid foundation, since it's open source and in the view of the public. Even within the runtime code base, you can find violations and inconsistencies - that's okay. There are bound to be inconsistencies, but those too (when and where applicable) could be addressed. Guidelines are a set of suggestions, not something that is mandated. You're free to ignore them.

Copy link

Choose a reason for hiding this comment

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

It is natural for them to morph over time

Yeah, I agree if there is a decent need to do so, or strong feedback from users. Could you point to the discussion about this newly added convention? Users want to know "why" this happened at this time.

And how about @nanasi880 's point?
#24054 (comment)

Copy link

@nanasi880 nanasi880 May 17, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

@IEvangelist
@SIkebe

I think it's too late to add these new guidelines after 20 years have passed since C# was born.

I agree with this.

It's not that I don't like the change, but the reason for the change is unclear, and as I pointed out, this is a change that Microsoft has explicitly denied.

It seems that static variables have an 's_' prefix and thread-static variables have 't_', what about AsyncLocal for example, and ThreadLocal?

Also, what if there are more of these in the future?
What if fiber is born? Is 'f_' the prefix that fiber local storage has?

We believe that history has proven that distinguishing these things by prepositions is a bad idea.
This is exactly what we call Hungarian notation, and we don't think it's an idea we should adopt, at least not actively now.


## Naming conventions

There are several naming conventions to consider when writing C# code.

### Pascal case

You should use pascal casing ("PascalCasing") when naming a `class`, `record`, or `struct`.
Use pascal casing ("PascalCasing") when naming a `class`, `record`, or `struct`.

```csharp
public class DataService
Expand Down Expand Up @@ -57,7 +58,7 @@ public interface IWorkerQueue
}
```

When naming `public` members of types, such as; fields, properties, events, methods, and local functions use pascal casing.
When naming `public` members of types, such as fields, properties, events, methods, and local functions, use pascal casing.

```csharp
public class ExampleEvents
Expand All @@ -81,7 +82,7 @@ public class ExampleEvents
}
```

When writing positional-records, use pascal casing for parameters as they're the public properties of the record.
When writing positional records, use pascal casing for parameters as they're the public properties of the record.

```csharp
public record PhysicalAddress(
Expand All @@ -91,11 +92,11 @@ public record PhysicalAddress(
string ZipCode);
```

For more information on positional-records, see [Positional syntax for property definition](../../language-reference/builtin-types/record.md#positional-syntax-for-property-definition).
For more information on positional records, see [Positional syntax for property definition](../../language-reference/builtin-types/record.md#positional-syntax-for-property-definition).

### Camel case

You should use camel casing ("camelCasing") when naming `private` or `internal` fields, and they should be prefixed with `_`.
Use camel casing ("camelCasing") when naming `private` or `internal` fields, and prefix them with `_`.

```csharp
public class DataService
Expand Down