Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 3 additions & 0 deletions docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,9 @@
]
},
"fileMetadata": {
"feedback_system": {
"docs/standard/design-guidelines/**/**.md": "None"
},
"feedback_product_url": {
"docs/fsharp/**/**.md": "https://github.com/Microsoft/visualfsharp"
},
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/abstract-class.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Abstract Class Design"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "type design guidelines, abstract classes"
Expand All @@ -10,8 +10,7 @@ helpviewer_keywords:
- "classes [.NET Framework], design guidelines"
- "type design guidelines, classes"
ms.assetid: d3646e6d-5c1f-4922-8fb0-ec5effb30d60
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Abstract Class Design
**X DO NOT** define public or protected internal constructors in abstract types.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
---
title: "Abstractions (Abstract Types and Interfaces)"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "interfaces [.NET Framework], abstract"
- "abstract interfaces [.NET Framework]"
- "abstract types [.NET Framework]"
- "types [.NET Framework], abstract"
ms.assetid: 0a632bc7-9b03-44ee-8842-c82f88672a45
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Abstractions (Abstract Types and Interfaces)
An abstraction is a type that describes a contract but does not provide a full implementation of the contract. Abstractions are usually implemented as abstract classes or interfaces, and they come with a well-defined set of reference documentation describing the required semantics of the types implementing the contract. Some of the most important abstractions in the .NET Framework include <xref:System.IO.Stream>, <xref:System.Collections.Generic.IEnumerable%601>, and <xref:System.Object>.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/arrays.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
---
title: "Arrays"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "class library design guidelines [.NET Framework], arrays"
- "arrays [.NET Framework], usage guidelines"
- "empty arrays"
ms.assetid: 66a1b3d8-6f3f-4715-b235-e1ff95e32d8e
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Arrays
**✓ DO** prefer using collections over arrays in public APIs. The [Collections](../../../docs/standard/design-guidelines/guidelines-for-collections.md) section provides details about how to choose between collections and arrays.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/attributes.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
---
title: "Attributes1"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "attributes [.NET Framework], about"
- "class library design guidelines [.NET Framework], attributes"
ms.assetid: ee0038ef-b247-4747-a650-3c5c5cd58d8b
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Attributes
<xref:System.Attribute?displayProperty=nameWithType> is a base class used to define custom attributes.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
---
title: "Base Classes for Implementing Abstractions"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "abstractions [.NET Framework]"
- "base classes, abstractions"
ms.assetid: 37a2d9a4-9721-482a-a40f-eee2c1d97875
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Base Classes for Implementing Abstractions
Strictly speaking, a class becomes a base class when another class is derived from it. For the purpose of this section, however, a base class is a class designed mainly to provide a common abstraction or for other classes to reuse some default implementation though inheritance. Base classes usually sit in the middle of inheritance hierarchies, between an abstraction at the root of a hierarchy and several custom implementations at the bottom.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/capitalization-conventions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Capitalization Conventions"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "camel-case names [.NET Framework]"
Expand All @@ -9,8 +9,7 @@ helpviewer_keywords:
- "case sensitivity, capitalization conventions"
- "names [.NET Framework], capitalization"
ms.assetid: 4c4ea526-9203-486f-b72d-29d61c5b3c6d
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Capitalization Conventions
The guidelines in this chapter lay out a simple method for using case that, when applied consistently, make identifiers for types, members, and parameters easy to read.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Choosing Between Class and Struct"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "class library design guidelines [.NET Framework], structures"
Expand All @@ -12,8 +12,7 @@ helpviewer_keywords:
- "classes [.NET Framework], vs. structures"
- "type design guidelines, classes"
ms.assetid: f8b8ec9b-0ba7-4dea-aadf-a93395cd804f
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Choosing Between Class and Struct
One of the basic design decisions every framework designer faces is whether to design a type as a class (a reference type) or as a struct (a value type). Good understanding of the differences in the behavior of reference types and value types is crucial in making this choice.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/common-design-patterns.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
---
title: "Common Design Patterns"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "design patterns in class libraries"
- "class library design guidelines [.NET Framework], design patterns"
ms.assetid: f7bd1361-4ab2-4132-972d-a044b8f197e1
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Common Design Patterns
There are numerous books on software patterns, pattern languages, and antipatterns that address the very broad subject of patterns. Thus, this chapter provides guidelines and discussion related to a very limited set of patterns that are used frequently in the design of the .NET Framework APIs.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/constructor.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Constructor Design"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "member design guidelines, constructors"
Expand All @@ -12,8 +12,7 @@ helpviewer_keywords:
- "default constructors"
- "static constructors"
ms.assetid: b4496afe-5fa7-4bb0-85ca-70b0ef21e6fc
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Constructor Design
There are two kinds of constructors: type constructors and instance constructors.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/dependency-properties.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
title: "Dependency Properties"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
ms.assetid: 212cfb1e-cec4-4047-94a6-47209b387f6f
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Dependency Properties
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.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
---
title: "Designing for Extensibility"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "extending class libraries"
- "extensibility with class libraries in .NET Framework"
- "class library design guidelines [.NET Framework], extensibility"
- "class library extensibility [.NET Framework]"
ms.assetid: 1cdb8740-871a-456c-9bd9-db96ca8d79b3
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Designing for Extensibility
One important aspect of designing a framework is making sure the extensibility of the framework has been carefully considered. This requires that you understand the costs and benefits associated with various extensibility mechanisms. This chapter helps you decide which of the extensibility mechanisms—subclassing, events, virtual members, callbacks, and so on—can best meet the requirements of your framework.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/dispose-pattern.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Dispose Pattern"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "Dispose method"
Expand All @@ -9,8 +9,7 @@ helpviewer_keywords:
- "customizing Dispose method name"
- "Finalize method"
ms.assetid: 31a6c13b-d6a2-492b-9a9f-e5238c983bcb
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Dispose Pattern
All programs acquire one or more system resources, such as memory, system handles, or database connections, during the course of their execution. Developers have to be careful when using such system resources, because they must be released after they have been acquired and used.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/enum.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Enum Design"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "type design guidelines, enumerations"
Expand All @@ -9,8 +9,7 @@ helpviewer_keywords:
- "class library design guidelines [.NET Framework], enumerations"
- "flags enumerations"
ms.assetid: dd53c952-9d9a-4736-86ff-9540e815d545
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Enum Design
Enums are a special kind of value type. There are two kinds of enums: simple enums and flag enums.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/equality-operators.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Equality Operators"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "class library design guidelines [.NET Framework], Equals method"
Expand All @@ -9,8 +9,7 @@ helpviewer_keywords:
- "Equals method"
- "== operator (equality) [.NET Framework]"
ms.assetid: bc496a91-fefb-4ce0-ab4c-61f09964119a
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Equality Operators
This section discusses overloading equality operators and refers to `operator==` and `operator!=` as equality operators.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/event.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Event Design"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "pre-events"
Expand All @@ -10,8 +10,7 @@ helpviewer_keywords:
- "post-events"
- "signatures, event handling"
ms.assetid: 67b3c6e2-6a8f-480d-a78f-ebeeaca1b95a
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Event Design
Events are the most commonly used form of callbacks (constructs that allow the framework to call into user code). Other callback mechanisms include members taking delegates, virtual members, and interface-based plug-ins. Data from usability studies indicate that the majority of developers are more comfortable using events than they are using the other callback mechanisms. Events are nicely integrated with Visual Studio and many languages.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/events-and-callbacks.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
---
title: "Events and Callbacks"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "events [.NET Framework], extensibility"
- "methods [.NET Framework], callback"
- "callback methods"
- "callbacks"
ms.assetid: 48b55c60-495f-4089-9396-97f9122bba7c
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Events and Callbacks
Callbacks are extensibility points that allow a framework to call back into user code through a delegate. These delegates are usually passed to the framework through a parameter of a method.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/exception-throwing.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
---
title: "Exception Throwing"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "exceptions, throwing"
- "explicitly throwing exceptions"
- "throwing exceptions, design guidelines"
ms.assetid: 5388e02b-52f5-460e-a2b5-eeafe60eeebe
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Exception Throwing
Exception-throwing guidelines described in this section require a good definition of the meaning of execution failure. Execution failure occurs whenever a member cannot do what it was designed to do (what the member name implies). For example, if the `OpenFile` method cannot return an opened file handle to the caller, it would be considered an execution failure.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/exceptions-and-performance.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Exceptions and Performance"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "tester-doer pattern"
Expand All @@ -9,8 +9,7 @@ helpviewer_keywords:
- "exceptions, performance"
- "throwing exceptions, performance"
ms.assetid: 3ad6aad9-08e6-4232-b336-0e301f2493e6
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Exceptions and Performance
One common concern related to exceptions is that if exceptions are used for code that routinely fails, the performance of the implementation will be unacceptable. This is a valid concern. When a member throws an exception, its performance can be orders of magnitude slower. However, it is possible to achieve good performance while strictly adhering to the exception guidelines that disallow using error codes. Two patterns described in this section suggest ways to do this.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/exceptions.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
---
title: "Design Guidelines for Exceptions"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "exceptions [.NET Framework], design guidelines"
- "class library design guidelines [.NET Framework], exceptions"
- "errors [.NET Framework], exceptions"
- "reporting errors"
ms.assetid: bc177b2f-7528-4ae4-83db-aacfb04b86d0
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Design Guidelines for Exceptions
Exception handling has many advantages over return-value-based error reporting. Good framework design helps the application developer realize the benefits of exceptions. This section discusses the benefits of exceptions and presents guidelines for using them effectively.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/extension-methods.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
title: "Extension Methods"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
ms.assetid: 5de945cb-88f4-49d7-b0e6-f098300cf357
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Extension Methods
Extension methods are a language feature that allows static methods to be called using instance method call syntax. These methods must take at least one parameter, which represents the instance the method is to operate on.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/field.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
---
title: "Field Design"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "fields, design guidelines"
- "read-only fields"
- "member design guidelines, fields"
ms.assetid: 7cb4b0f3-7a10-4c93-b84d-733f7134fcf8
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Field Design
The principle of encapsulation is one of the most important notions in object-oriented design. This principle states that data stored inside an object should be accessible only to that object.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/general-naming-conventions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "General Naming Conventions"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
helpviewer_keywords:
- "names [.NET Framework], conflicts"
Expand All @@ -14,8 +14,7 @@ helpviewer_keywords:
- "names [.NET Framework], type names"
- "names [.NET Framework], acronyms"
ms.assetid: d3a77ea1-75d2-4969-a8c3-3e1e3e1aaedc
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# General Naming Conventions
This section describes general naming conventions that relate to word choice, guidelines on using abbreviations and acronyms, and recommendations on how to avoid using language-specific names.
Expand Down
5 changes: 2 additions & 3 deletions docs/standard/design-guidelines/guidelines-for-collections.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
title: "Guidelines for Collections"
ms.date: "03/30/2017"
ms.date: "10/22/2008"
ms.technology: dotnet-standard
ms.assetid: 297b8f1d-b11f-4dc6-960a-8e990817304e
author: "rpetrusha"
ms.author: "ronpet"
author: "KrzysztofCwalina"
---
# Guidelines for Collections
Any type designed specifically to manipulate a group of objects having some common characteristic can be considered a collection. It is almost always appropriate for such types to implement <xref:System.Collections.IEnumerable> or <xref:System.Collections.Generic.IEnumerable%601>, so in this section we only consider types implementing one or both of those interfaces to be collections.
Expand Down
Loading