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

Author: Krzysztof Cwalina, Brad Abrams
4.6
All Stack Overflow 48
This Year Stack Overflow 2
This Month Stack Overflow 1

Comments

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

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.