Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

Category: Programming
Author: Krzysztof Cwalina, Brad Abrams
All Stack Overflow 48
This Year Stack Overflow 2
This Month Stack Overflow 14


by Kev   2019-07-21

The Framework Design Guidelines book (first edition) by Krzysztof Cwalina and Brad Abrams recommend throwing existing exceptions defined in the System namespaces where you can, and the more specific the better. If there isn't a good fit then throw a custom exception.

Creating a parallel universe of CustomArgumentNullException to match System.ArgumentNullException is a duplication of effort that I don't see any value in. At the end of the day if your code throws a System.ArgumentNullException rather than a framework class you can determine from the stack trace who was ultimately responsible.

This smells of unnecessary extra work for the present and in the future when it comes to code maintenance time.

by Matt Schwartz   2019-07-21

Sounds like you could benefit (and enjoy!) from reading this...

by Kev   2019-07-21

Example 2 is without a doubt the least error prone approach. Please see this answer I gave to a similar question for the reason why:

What is the prefered style for single decision and action statements?

Although the Visual Studio default for brace usage is to put braces on a newline (my preferred method), the Framework Design Guidelines book (first edition) by Krzysztof Cwalina and Brad Abrams propose a different convention, example 4, placing the opening brace at the end of a preceding if statement (Page 274). They also state "Avoid omitting braces, even if the language allows it".

Not having the second edition at hand, I couldn't say if these conventions have changed or not.

by anonymous   2019-07-21

These were in the Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries book, first published in 2005 - there are relevant excerpts on MSDN. These set to deprecate Hungarian notation, as that had got misused over the years for exposed names in .Net frameworks.

by anonymous   2019-07-21

No it is not common to use getter /setter style names in C#. Properties should be used for almost all places you would use a getter / setter in Java.

IMHO, the defacto standard for naming conventions comes from the Framework Design Guidelines. It's enforced by several tools (FxCop) and is the dominant style of many libraries including the BCL.

by aku   2018-03-19

I want to clarify this situation.

According to Microsoft guidelines, it's a good practice to provide Close method where suitable. Here is a citation from Framework design guidelines

Consider providing method Close(), in addition to the Dispose(), if close is standard terminology in the area. When doing so, it is important that you make the Close implementation identical to Dispose ...

In most of cases Close and Dispose methods are equivalent. The main difference between Close and Dispose in the case of SqlConnectionObject is:

An application can call Close more than one time. No exception is generated.

If you called Dispose method SqlConnection object state will be reset. If you try to call any method on disposed SqlConnection object, you will receive exception.

That said:

  • If you use connection object one time, use Dispose.
  • If connection object must be reused, use Close method.
by Bernd   2017-08-20

The Framework Design Guidelines suggest returning a copy of the Array. That way, consumers can't change items from the array.

// bad code
// could still do Path.InvalidPathChars[0] = 'A';
public sealed class Path {
   public static readonly char[] InvalidPathChars = 
      { '\"', '<', '>', '|' };

these are better:

public static ReadOnlyCollection<char> GetInvalidPathChars(){
   return Array.AsReadOnly(InvalidPathChars);

public static char[] GetInvalidPathChars(){
   return (char[])InvalidPathChars.Clone();

The examples are straight from the book.

by anonymous   2017-08-20

Dupe: there is another question on SO just like this: Abstract class constructor access modifier

The answers on that question come down to the same thing in the end: it does not really matter if you declare it protected or public.

Also there seems to be some discussion about it in literature (e.g. in Framework Design Guidelines). This is referenced in this blogpost: Good design or bad design of abstract class?

by anonymous   2017-08-20

From Microsoft Constructor Design Guidelines (MSDN),

Do throw exceptions from instance constructors if appropriate.

Constructors should throw and handle exceptions like any method. Specifically, a constructor should not catch and hide any exceptions that it cannot handle.

Factory Method is not the right way to approach this problem. See Constructors vs Factory Methods

From Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

5.3 Constructor Design

Consider using a static factory method instead of a constructor if the semantics of the desired operation do not map directly to the construction of a new instance, or if following the constructor design guidelines feels unnatural.

Do throw exceptions from instance constructors if appropriate.

.NET BCL implementations do throw exceptions from constructors

For example, the List Constructor (Int32), throws an ArgumentOutOfRangeException when the capacity argument of the list is negative.

var myList = new List<int>(-1); // throws ArgumentOutOfRangeException

Similarly, your constructor should throw an appropriate type of exception when it reads the file. For example, it could throw FileNotFoundException if the file does not exist at the specified location, etc.

More Information

  • Code Contracts
  • Throwing exceptions from constructor in .Net
  • Throwing ArgumentNullException in constructor?
  • Constructor parameter validation in C# - Best practices
by anonymous   2017-08-20

According to MS standards your code is OK. Having prefixes as m_ is not really necessary when you have advanced IDE. However short prefix like _ can be used to take advantage of auto complete feature to quickly sort out class members.

I would recommend you to get a copy of "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book to learn more on MS standards

by anonymous   2017-08-20

The significant point is that the variable name "should not" represent its type. Instead, It should indicate the "business semantic" of the variable; The type of the variable is subject to change during the code maintenance, but the semantics of that variable is rarely changed.

Incorporating "StyleCop" into your development lifecycle can enforce consistent code style amongst team members.

UPDATE: This excerpt from the Chapter 3 of "Framework Design Guidelines" which is dedicated to "Naming Guidelines" helps to clarify the issue:

Identifier names should clearly state what each member does and what each type and parameter represents. To this end, it is more important that name be clear than that it be short. Names should correspond to scenarios , logical or physical parts of the system, and well-known concepts rather than to technologies or architecture.

DO choose easily readable identifier names.[...]

DO favor readability over brevity.[...]

DO NOT use underscores, hyphens, or any other non-alphanumeric characters.[...]

DO NOT use Hungrian Notation. [...]

by anonymous   2017-08-20

The short answer is: nowhere.

It is a relic of the past, where Microsoft intended developers to inherit all their custom exceptions from ApplicationException. Shortly after, they changed their mind and advised that custom exceptions should derive from the base Exception class. See Best Practices for Handling Exceptions on MSDN.

One of the more widely circulated reasons for this comes from an exerpt from Jeffery Richter in Framework Design Guidelines:

System.ApplicationException is a class that should not be part of the .NET Framework. The original idea was that classes derived from SystemException would indicate exceptions thrown from the CLR (or system) itself, whereas non-CLR exceptions would be derived from ApplicationException. However, a lot of exception classes didn't follow this pattern. For example, TargetInvocationException (which is thrown by the CLR) is derived from ApplicationException. So, the ApplicationException class lost all meaning. The reason to derive from this base class is to allow some code higher up the call stack to catch the base class. It was no longer possible to catch all application exceptions.

So there you have it. The executive summary is that ApplicationException is not harmful, just useless.