revert changes to design guidelines (#46447)

Author: gewarren

docs/standard/design-guidelines/arrays.md

@@ -18,7 +18,7 @@ helpviewer_keywords:
 
  ✔️ CONSIDER using jagged arrays instead of multidimensional arrays.
 
- A jagged array is an array with elements that are also arrays. The arrays that make up the elements can be of different sizes, leading to less wasted space for some sets of data (for example, sparse matrix) compared to multidimensional arrays. Furthermore, the CLR optimizes index operations on jagged arrays, so they might exhibit better runtime performance in some scenarios.
+ A jagged array is an array with elements that are also arrays. The arrays that make up the elements can be of different sizes, leading to less wasted space for some sets of data (e.g., sparse matrix) compared to multidimensional arrays. Furthermore, the CLR optimizes index operations on jagged arrays, so they might exhibit better runtime performance in some scenarios.
 
  *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.*
 

docs/standard/design-guidelines/dependency-properties.md

@@ -10,7 +10,7 @@ ms.assetid: 212cfb1e-cec4-4047-94a6-47209b387f6f
 
 A dependency property (DP) is a regular property that stores its value in a property store instead of storing it in a type variable (field), for example.
 
- An attached dependency property is a kind of dependency property modeled as static Get and Set methods representing "properties" describing relationships between objects and their containers (for example, the position of a `Button` object on a `Panel` container).
+ An attached dependency property is a kind of dependency property modeled as static Get and Set methods representing "properties" describing relationships between objects and their containers (e.g., the position of a `Button` object on a `Panel` container).
 
  ✔️ DO provide the dependency properties, if you need the properties to support WPF features such as styling, triggers, data binding, animations, dynamic resources, and inheritance.
 

docs/standard/design-guidelines/dispose-pattern.md

@@ -26,7 +26,7 @@ All programs acquire one or more system resources, such as memory, system handle
 
  Although finalizers are effective in some cleanup scenarios, they have two significant drawbacks:
 
-- The finalizer is called when the GC detects that an object is eligible for collection. This happens at some undetermined period of time after the resource is not needed anymore. The delay between when the developer could or would like to release the resource and the time when the resource is actually released by the finalizer might be unacceptable in programs that acquire many scarce resources (resources that can be easily exhausted) or in cases in which resources are costly to keep in use (for example, large unmanaged memory buffers).
+- The finalizer is called when the GC detects that an object is eligible for collection. This happens at some undetermined period of time after the resource is not needed anymore. The delay between when the developer could or would like to release the resource and the time when the resource is actually released by the finalizer might be unacceptable in programs that acquire many scarce resources (resources that can be easily exhausted) or in cases in which resources are costly to keep in use (e.g., large unmanaged memory buffers).
 
 - When the CLR needs to call a finalizer, it must postpone collection of the object’s memory until the next round of garbage collection (the finalizers run between collections). This means that the object’s memory (and all objects it refers to) will not be released for a longer period of time.
 
@@ -78,7 +78,7 @@ public class DisposableResourceHolder : IDisposable {
 }
 ```
 
- The Boolean parameter `disposing` indicates whether the method was invoked from the `IDisposable.Dispose` implementation or from the finalizer. The `Dispose(bool)` implementation should check the parameter before accessing other reference objects (for example, the resource field in the preceding sample). Such objects should only be accessed when the method is called from the `IDisposable.Dispose` implementation (when the `disposing` parameter is equal to true). If the method is invoked from the finalizer (`disposing` is false), other objects should not be accessed. The reason is that objects are finalized in an unpredictable order and so they, or any of their dependencies, might already have been finalized.
+ The Boolean parameter `disposing` indicates whether the method was invoked from the `IDisposable.Dispose` implementation or from the finalizer. The `Dispose(bool)` implementation should check the parameter before accessing other reference objects (e.g., the resource field in the preceding sample). Such objects should only be accessed when the method is called from the `IDisposable.Dispose` implementation (when the `disposing` parameter is equal to true). If the method is invoked from the finalizer (`disposing` is false), other objects should not be accessed. The reason is that objects are finalized in an unpredictable order and so they, or any of their dependencies, might already have been finalized.
 
  Also, this section applies to classes with a base that does not already implement the Dispose Pattern. If you are inheriting from a class that already implements the pattern, simply override the `Dispose(bool)` method to provide additional resource cleanup logic.
 

docs/standard/design-guidelines/extension-methods.md

@@ -36,7 +36,7 @@ Extension methods are a language feature that allows static methods to be called
 
  ❌ DO NOT define extension methods implementing a feature in namespaces normally associated with other features. Instead, define them in the namespace associated with the feature they belong to.
 
- ❌ AVOID generic naming of namespaces dedicated to extension methods (for example, "Extensions"). Use a descriptive name (for example, "Routing") instead.
+ ❌ AVOID generic naming of namespaces dedicated to extension methods (e.g., "Extensions"). Use a descriptive name (e.g., "Routing") instead.
 
  *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.*
 

docs/standard/design-guidelines/guidelines-for-collections.md

@@ -44,11 +44,11 @@ Any type designed specifically to manipulate a group of objects having some comm
 
  ✔️ DO use `Collection<T>` or a subclass of `Collection<T>` for properties or return values representing read/write collections.
 
- If `Collection<T>` does not meet some requirement (for example, the collection must not implement <xref:System.Collections.IList>), use a custom collection by implementing `IEnumerable<T>`, `ICollection<T>`, or <xref:System.Collections.Generic.IList%601>.
+ If `Collection<T>` does not meet some requirement (e.g., the collection must not implement <xref:System.Collections.IList>), use a custom collection by implementing `IEnumerable<T>`, `ICollection<T>`, or <xref:System.Collections.Generic.IList%601>.
 
  ✔️ DO use <xref:System.Collections.ObjectModel.ReadOnlyCollection%601>, a subclass of `ReadOnlyCollection<T>`, or in rare cases `IEnumerable<T>` for properties or return values representing read-only collections.
 
- In general, prefer `ReadOnlyCollection<T>`. If it does not meet some requirement (for example, the collection must not implement `IList`), use a custom collection by implementing `IEnumerable<T>`, `ICollection<T>`, or `IList<T>`. If you do implement a custom read-only collection, implement `ICollection<T>.IsReadOnly` to return `true`.
+ In general, prefer `ReadOnlyCollection<T>`. If it does not meet some requirement (e.g., the collection must not implement `IList`), use a custom collection by implementing `IEnumerable<T>`, `ICollection<T>`, or `IList<T>`. If you do implement a custom read-only collection, implement `ICollection<T>.IsReadOnly` to return `true`.
 
  In cases where you are sure that the only scenario you will ever want to support is forward-only iteration, you can simply use `IEnumerable<T>`.
 
@@ -78,7 +78,7 @@ Any type designed specifically to manipulate a group of objects having some comm
 
  ✔️ DO use either a snapshot collection or a live `IEnumerable<T>` (or its subtype) to represent collections that are volatile (i.e., that can change without explicitly modifying the collection).
 
- In general, all collections representing a shared resource (for example, files in a directory) are volatile. Such collections are very difficult or impossible to implement as live collections unless the implementation is simply a forward-only enumerator.
+ In general, all collections representing a shared resource (e.g., files in a directory) are volatile. Such collections are very difficult or impossible to implement as live collections unless the implementation is simply a forward-only enumerator.
 
 ## Choosing Between Arrays and Collections
 
@@ -92,7 +92,7 @@ Any type designed specifically to manipulate a group of objects having some comm
 
  ✔️ DO use byte arrays instead of collections of bytes.
 
- ❌ DO NOT use arrays for properties if the property would have to return a new array (for example, a copy of an internal array) every time the property getter is called.
+ ❌ DO NOT use arrays for properties if the property would have to return a new array (e.g., a copy of an internal array) every time the property getter is called.
 
 ## Implementing Custom Collections
 
@@ -110,7 +110,7 @@ Any type designed specifically to manipulate a group of objects having some comm
 
 ### Naming Custom Collections
 
- Collections (types that implement `IEnumerable`) are created mainly for two reasons: (1) to create a new data structure with structure-specific operations and often different performance characteristics than existing data structures (for example,  <xref:System.Collections.Generic.List%601>, <xref:System.Collections.Generic.LinkedList%601>, <xref:System.Collections.Generic.Stack%601>), and (2) to create a specialized collection for holding a specific set of items (for example,  <xref:System.Collections.Specialized.StringCollection>). Data structures are most often used in the internal implementation of applications and libraries. Specialized collections are mainly to be exposed in APIs (as property and parameter types).
+ Collections (types that implement `IEnumerable`) are created mainly for two reasons: (1) to create a new data structure with structure-specific operations and often different performance characteristics than existing data structures (e.g.,  <xref:System.Collections.Generic.List%601>, <xref:System.Collections.Generic.LinkedList%601>, <xref:System.Collections.Generic.Stack%601>), and (2) to create a specialized collection for holding a specific set of items (e.g.,  <xref:System.Collections.Specialized.StringCollection>). Data structures are most often used in the internal implementation of applications and libraries. Specialized collections are mainly to be exposed in APIs (as property and parameter types).
 
  ✔️ DO use the "Dictionary" suffix in names of abstractions implementing `IDictionary` or `IDictionary<TKey,TValue>`.
 

docs/standard/design-guidelines/names-of-classes-structs-and-interfaces.md

@@ -28,7 +28,7 @@ The naming guidelines that follow apply to general type naming.
 
  Nouns and noun phrases should be used rarely and they might indicate that the type should be an abstract class, and not an interface.
 
- ❌ DO NOT give class names a prefix (for example, "C").
+ ❌ DO NOT give class names a prefix (e.g., "C").
 
  ✔️ CONSIDER ending the name of derived classes with the name of the base class.
 
@@ -94,7 +94,7 @@ public interface ISessionChannel<TSession> where TSession : ISession {
 
  ❌ DO NOT use "Flag" or "Flags" suffixes in enum type names.
 
- ❌ DO NOT use a prefix on enumeration value names (for example, "ad" for ADO enums, "rtf" for rich text enums, etc.).
+ ❌ DO NOT use a prefix on enumeration value names (e.g., "ad" for ADO enums, "rtf" for rich text enums, etc.).
 
  *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.*
 

docs/standard/design-guidelines/names-of-namespaces.md

@@ -29,7 +29,7 @@ As with other naming guidelines, the goal when naming namespaces is creating suf
 
  ❌ DO NOT use organizational hierarchies as the basis for names in namespace hierarchies, because group names within corporations tend to be short-lived. Organize the hierarchy of namespaces around groups of related technologies.
 
- ✔️ DO use PascalCasing, and separate namespace components with periods (for example, `Microsoft.Office.PowerPoint`). If your brand employs nontraditional casing, you should follow the casing defined by your brand, even if it deviates from normal namespace casing.
+ ✔️ DO use PascalCasing, and separate namespace components with periods (e.g., `Microsoft.Office.PowerPoint`). If your brand employs nontraditional casing, you should follow the casing defined by your brand, even if it deviates from normal namespace casing.
 
  ✔️ CONSIDER using plural namespace names where appropriate.
 

docs/standard/design-guidelines/property.md

@@ -53,7 +53,7 @@ Although properties are technically very similar to methods, they are quite diff
 
  If the design requires other types of parameters, strongly reevaluate whether the API really represents an accessor to a logical collection. If it does not, use a method. Consider starting the method name with `Get` or `Set`.
 
- ✔️ DO use the name `Item` for indexed properties unless there is an obviously better name (for example, see the <xref:System.String.Chars%2A> property on `System.String`).
+ ✔️ DO use the name `Item` for indexed properties unless there is an obviously better name (e.g., see the <xref:System.String.Chars%2A> property on `System.String`).
 
  In C#, indexers are by default named Item. The <xref:System.Runtime.CompilerServices.IndexerNameAttribute> can be used to customize this name.
 

docs/standard/design-guidelines/usage-guidelines.md

@@ -2,14 +2,14 @@
 description: "Learn more about: Usage guidelines"
 title: "Usage guidelines"
 ms.date: "10/22/2008"
-helpviewer_keywords:
+helpviewer_keywords: 
   - "class library design guidelines [.NET Framework], usage guidelines"
 ms.assetid: 42215ffa-a099-4a26-b14e-fb2bdb6f95b7
 ---
 # Usage guidelines
 
-This section contains guidelines for using common types in publicly accessible APIs. It deals with direct usage of built-in Framework types (for example, serialization attributes) and overloading common operators.
-
+This section contains guidelines for using common types in publicly accessible APIs. It deals with direct usage of built-in Framework types (e.g., serialization attributes) and overloading common operators.
+  
 The <xref:System.IDisposable?displayProperty=nameWithType> interface is not covered in this section, but is discussed in the [Dispose Pattern](dispose-pattern.md) section.
 
 > [!NOTE]
@@ -27,7 +27,7 @@ The <xref:System.IDisposable?displayProperty=nameWithType> interface is not cove
 *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.*
 
 *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.*
-
+  
 ## See also
 
 - [Framework Design Guidelines](index.md)