.Net Framework Design Guidelines


Do NotReturn error codes.
DoReport execution failures by throwing exceptions.
ConsiderTerminating the process by calling System.Environment.FailFast (.net 2.0) instead of throwing an exception, if your code encounters a situation where it is unsafe for further execution.
Do NotUse exceptions for the normal flow of control, if possible.
ConsiderThe performance implications of throwing exceptions.
DoDocument all exceptions thrown by publicly callable members because of a violation of the member contract (rather than a system failure) and treat them as part of your contract.
Do NotHave public members that can either throw or not based on some option.
Do NotHave public members that return exceptions as the return value or an out parameter.
ConsiderUsing exception builder methods.
Do NotThrow exceptions from exception filter blocks.
AvoidExplicitly throwing exceptions from finally blocks.
ConsiderThrowing existing exceptions residing in the System namespaces instead of creating custom exception types.
DoCreate and throw custom exceptions if you have an error condition that can be programmatically handled in a different way than any other existing exception.
Do NotCreate and throw new exceptions just to have your team's exception.
DoThrow the most specific (the most derived) exception that makes sense.
DoProvide a rich and meaningful message text targeted at the developer when throwing an exception.
DoEnsure that exception messages are grammatically correct.
DoEnsure that each sentence of the message text ends with a period.
AvoidQuestion marks and exclamation points in exception messages.
Do NotDisclose security-sensitive information in exception messages without demanding appropriate permissions.
ConsiderLocalizing the exception messages thrown by your component if you expect your components to be used by developers speaking different languages.
Do NotSwallow errors by catching nonspecific exceptions, such as System.Exception, System.SystemException, and so on in framework code.
AvoidSwallowing errors by catching nonspecific exceptions, such as System.Exception, System.SystemException, and so on in application code.
Do NotExclude any special exceptions when catching for the purpose of transferring exceptions.
ConsiderCatching a specific exception when you understand why it was thrown in a given context and can respond to the failure programmatically.
Do NotOvercatch. Exceptions should often be allowed to propagate up the call stack.
DoUse try-finally and avoid using try-catch for cleanup code.
DoPrefer using an empty throw when catching and rethrowing an exception.
Do NotHandle non-CLS-compliant exceptions (exceptions that don't derive from System.Exception) using a parameterless catch block.
ConsiderWrapping specific exceptions thrown from a lower layer in a more appropriate exception, if the lower layer exception does not make sense in the context of the higher layer operation.
AvoidCatching and wrapping nonspecific exceptions.
DoSpecify the inner exception when wrapping exceptions.
Do NotThrow System.Exception or System.SystemException
Do NotCatch System.Exception or System.SystemException in framework code, unless you intend to rethrow.
AvoidCatching System.Exception or System.SystemException, except in top-level exception handlers.
Do NotThrow or derive from System.ApplicationException.
DoThrow an InvalidOperationException if the object is in an inappropriate state.
DoThrow ArgumentException or one of its subtypes if bad arguments are passed to a member.
DoSet the ParamName property when throwing one of the ArgumentExceptions.
DoUse value for the name of the implicit value parameter of property setters.
Do NotAllow publicly callable APIs to explicitly or implicitly throw NullReferenceException, AccessViolationException, or IndexOutOfRangeException.
Do NotExplicitly throw StackOverflowException.
Do NotCatch StackOverflowException.
Do NotExplicitly throw OutOfMemoryException.
Do NotExplicitly throw InteropException, ComException, and SEHException.
Do NotCatch SEHException explicitly.
AvoidDeep exception hierarchies.
DoDerive exceptions from System.Exception or one of the other common base exceptions.
DoEnd exception class names with the “Exception” suffix.
DoMake exceptions serializable.
DoProvide (at least) these common constructors on all exceptions: 1. public SomeException(); 2. public SomeException(string message); 3. public SomeException(string message, Exception inner); 4. protected SomeException(SerializationInfo info, StreamingContext context);
DoReport security-sensitive information through an override of ToString only after demanding an appropriate permission.
DoStore useful security-sensitive information in a private exception state.
ConsiderProviding exception properties for programmatic access to extra information (besides the message string) relevant to the exception.
Do NotUse error codes because of concerns that exceptions might affect performance negatively.
ConsiderThe Tester-Doer Pattern for members that might throw exceptions in common scenarios to avoid performance problems related to exceptions.
ConsiderThe Try-Parse Pattern for members that might throw exceptions in common scenarios to avoid performance problems related to exceptions.
DoUse the prefix “Try” and Boolean return type for methods implementing this Pattern.
DoProvide an exception-throwing member for each member using the Try-Parse Pattern.