Ambiguous statment - Comment style - Why avoid multi-line comments (/* */) for longer explanations

dylan-george-field commented 1 month ago

Type of issue

Missing information

Description

Comments aren't localized. Instead, longer explanations are in the companion article.

This statement is ambiguous.

Localized to what?
- Language
- Culture
- Team
- Organisation
- File
What companion article?
- External Link
- Readme
- File
- Swagger
- Microsoft Lean Article

Page URL

https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions

Content source URL

https://github.com/dotnet/docs/blob/main/docs/csharp/fundamentals/coding-style/coding-conventions.md

Document Version Independent Id

f940f2ad-e13d-4d37-6439-f8afcbc4e4c7

Article author

@BillWagner

Metadata

ID: 40f42506-f4a5-859a-0266-ded002056d83
Service: dotnet-csharp
Sub-service: fundamentals

BillWagner commented 1 month ago

Thanks for pointing this out @dylan-george-field

To clarify: By "localization", we mean localizing the text for the Learn platform. Comments in code samples aren't translated. Comments are rendered in English in all translated versions of the Learn site.

For that reason, we require explanatory text to be in the markdown file for the article. Where necessary, that text can be duplicated in code, but the comments can't be the only explanation.

I'll add this to our backlog, and add the "help wanted" tag if anyone gets to make an update before we get to this this article.

BartoszKlonowski commented 1 month ago

@BillWagner I will work on that!

dotnet / docs