C# 3.0 Coding Guidelines Guidelines for .NET development March 2009 Dennis Doomen www.avivasolutions.nl blog.avivasolutions.nl C# 3.0 Coding Guidelines Guidelines for .NET Development Contents 1 General ........................................................................................................................................... 1 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 Introduction ............................................................................................................................................. 1 Goals ...................................................................................................................................................... 1 Visual Studio Code Analysis and Source Analysis ................................................................................. 1 Guidelines, not a standard ...................................................................................................................... 1 What about design patterns? .................................................................................................................. 2 Feedback and disclaimer ........................................................................................................................ 2 Contributions .......................................................................................................................................... 2 History .................................................................................................................................................... 2 2 3 4 5 6 7 8 9 Design Guidelines ......................................................................................................................... 3 Maintainability Guidelines ........................................................................................................... 8 Naming Guidelines ..................................................................................................................... 15 Performance Guidelines ............................................................................................................ 19 Usage Guidelines ........................................................................................................................ 20 Documentation Guidelines ........................................................................................................ 22 Layout Guidelines ....................................................................................................................... 24 Resources .................................................................................................................................... 26 10 List of Code Analysis Rules ...................................................................................................... 27 March 2009 Dennis Doomen [ II ] www.avivasolutions.nl blog.avivasolutions.nl C# 3.0 Coding Guidelines Guidelines for .NET Development 1 1.1 General Introduction This document attempts to provide useful and pragmatic guidelines for programming in C# 3.0 which we at Aviva Solutions already use in our day-to-day work. This idea started in 2002 when Vic Hartog (Philips Medical Systems) and I were assigned the task of writing up a coding standard for C# 1.0. Since then, I've tried to publish a similar document for C# 2.0, but because of a change of employer, I never officially published it other than through blog posts. In the last couple of months I’ve received several requests from the community for an updated version of this document, preferably covering C# 3.0 as well. Moreover, I have become particularly fond of the power that Visual Studio's Code Analysis (FxCop) provides. 1.2 Goals The coding guidelines have been written up for several reasons that should help writing high quality code that is easy to understand code and easy to maintain by (future) team members. Aviva Solutions applies code reviews to validate code quality, so it is important that all members of a project use the same style of coding. Style in this sense means using common constructs, writing proper documentation and code comments, and organizing code using a common layout. Although complying with coding guidelines may seem to appear as undesired overhead or may limit creativity, this approach has already proven its value for many years. Moreover, not all coding guidelines have a clear rationale. Many of them are simply choices we made at Aviva Solutions. Additional goals include: 1.3 Preventing common mistakes and pitfalls. Preventing language constructs that are less comprehensive. Promoting object-oriented development. Visual Studio Code Analysis and Source Analysis Since the introduction of the first version of this document, Microsoft has spent a considerable amount of effort in helping us automating the review process. Static Code Analysis (FxCop) supports a wide range of rules covering both aspects such as this document covers and design guidelines on the usage of the .NET Framework. In this edition of the coding guidelines, we've removed all overlap with Code Analysis and added a list of recommended rules. Another more recent effort is Source Analysis, a.k.a. StyleCop. But even though we really like it, its current ruleset does not allow sufficient flexibility to be pragmatic. For instance, we do want all public members to have proper documentation, but for many private members we don't need one. The current version of StyleCop does not allow you to choose this as an option yet. 1.4 Guidelines, not a standard The document does not state that projects must comply with these guidelines, neither does it say which guidelines are more important than others. However, we encourage projects to decide themselves what guidelines are important, what deviations a project will use, who is the consultant in case doubts arise, and what kind of layout must be used for source code. Obvious, you should make these decisions before starting the real coding work. In general, generated code should not need to comply with coding guidelines. However, if it is possible to modify the templates used for generation, try to make them generate code that complies as much as possible. March 2009 Dennis Doomen [1] www.avivasolutions.nl blog.avivasolutions.nl articles and on-line discussions): Erwin Derksen (Ordina). 1. However.0 Standard Major overhaul.0 Coding Guidelines Guidelines for .avivasolutions.7 Contributions The following (prior) colleagues and members from the . adapt. Introduced recommended use of Code Analysis / FxCop and removed overlapping guidelines. comments or suggestions. Jimmy Nilsson and Jeremy D. Vic Hartog (Philips Medical Systems).nl .nl blog. and redistribute this document and its companion quick reference guide for noncommercial purposes or internal usage. Leendert Versluijs (Ordina).5 What about design patterns? We've received a few suggestions that were great on itself. It is allowed to copy. Jo-Wen Mei (Oosterkamp Training) 1. or publish or distribute any adaptation of this document for commercial use without first obtaining express written approval from Aviva Solutions. Miller. William van Strien (Ordina). Added C# 3. Notice though that it merely reflects our view on proper C# code so Aviva Solutions will not be liable for any direct or indirect damages caused by applying the guidelines of this document.6 Feedback and disclaimer This document has been compiled using many contributions from both (ex) colleagues.0 / LINQ coding guidelines. I'd like to refer you to notable people like Martin Fowler. Juwal Lovy (IDesign).avivasolutions. Stephan Bookholt (Aviva Solutions). Instead. Martin Opdam (Aviva Solutions).NET community have contributed to this document both directly and indirectly (through web sites. Mar 2009 First publication on the internet Dennis Doomen Dennis Doomen Dennis Doomen March 2009 Dennis Doomen [2] www. John Dekkers (Ordina). and many years of developing in C#. you may not republish this document. We will try to revise and republish this document with new insights. If you have questions. Even though I would love to to add these as well.C# 3. 1.8 History Jan 2006 Jan 2009 Initial version based on the Philips C# 1. Peter Ritchie (Independent MVP). please let us know by sending me an email at dennis. experiences and remarks on a regular basis. sources from the Internet. Matthijs den Haan (Ordina).NET Development 1. it would have increased the size of the document significantly.nl.doomen@avivasolutions. but unfortunately where too much related to design principles and patterns. and blue components and this class has a constructor taking a numeric representation. etc). For example: public static class EuroConversion { public static Decimal FromUSD(Decimal inUsd) { .C# 3. defined virtual methods and properties. public static readonly Color White = new Color(0xFFFFFF). consider a Color struct that stores a color internally as red. define the class sealed.nl . public static readonly Color Black = new Color(0x000000).NET Development 2 AV1001 Design Guidelines Do use a public static readonly field to define predefined object instances For example. one of the most essential object-orientation principles.. public struct Color { public static readonly Color Red = new Color(0xFF0000). defined protected default constructors. public Color(int redGreenBlue) { // implementation } } AV1002 Do mark classes that only contain static members as static The advantage of using a static class is that the compiler can make sure that no instance members are accidentally defined.avivasolutions. Consider the following two classes: public class Book { public virtual void Print() { Console.avivasolutions. The compiler will guarantee that instances of this class cannot be created and hence.nl blog.0 Coding Guidelines Guidelines for .. } public static Decimal ToUSD(Decimal inEuro) { . relieves you of creating a private constructor such as was required in C# 1. it also makes subclasses more difficult to understand. } } AV1003 Do seal a class unless it has been designed for inheritance Defining a class sealed ensures that other classes cannot derive from it. then this class may expose several predefined colors like this.WriteLine("Printing Book").. } } public class PocketBook : Book { March 2009 Dennis Doomen [3] www. Unless you have thought through the consequences of deriving from your class and have provided appropriate measurements (e.. green. For example: public sealed class Book { public Book() { … } } AV1010 Don’t hide inherited members with the new keyword Not only does the new keyword break Polymorphism. Use a static class to contain methods that are not associated with a particular instance.g.0. there should not be a difference between first setting property DataSource and then DataMember. } } This will cause the following behavior which is not something you normally expect from class hierarchies. The operation returns a copy of an internal state (this does not include copies of value type objects returned on the stack). For example. The operation has a significant and observable side effect. In particular. not properties. operations that access the network or the file system (other than once for initialization) should most likely be methods. A private constructor is exempt from this rule. AV1015 Do allow properties to be set in any order Properties should be stateless with respect to other properties. an ICollection<T>. rather than a property. even if the parameters didn’t change.nl blog.WriteLine("Printing PocketBook"). such as the Object.NET Development public new void Print() { Console. it shall be possible to use a reference to an object of a derived class wherever a reference to its base class object is used without knowing the specific derived class. This may cause unexpected effects within the class that owns the array. they can still replace an item within the array with another item. ((Book)pocketBook). in the following situations The operation is orders of magnitude slower than a field set would be.Print(). pocketBook. the NewGuid method returns a different value each time it is called. Even though callers cannot replace the array itself with another array. i.avivasolutions. AV1016 Do use a method. This rule is also known as the Liskov Substitution Principle (LSP). AV1025 Don’t return an array This allows calling code to change the items in the array. Book pocketBook = new PocketBook(). Instead. or.nl .e.ToString method.Print().avivasolutions. it is very likely that the operation is too expensive to be a property. return an IEnumerable<T>. Please note that an interface is also regarded as a base class in this context. If you are even considering providing an asynchronous version of an operation to avoid blocking the thread.C# 3. There shall be no need to set additional properties. AV1011 It should be possible to treat a derived object as if it were a base class object In other words.0 Coding Guidelines Guidelines for . March 2009 Dennis Doomen [4] www. AV1020 Don’t create a constructor that does not yield a fully initialized object Only create constructors that construct objects that are fully initialized. if the number of items is important for the caller. // Will output "Printing PocketBook " // Will output "Printing Book" It should not make a difference whether you call Print through the base class or the derived class. The operation returns a different result each time it is called. The operation is a conversion. Note that populating an internal cache is not generally considered an observable side effect. and vice versa. AV1043 Prefer throwing existing exceptions Use existing exceptions residing in the System namespaces instead of creating custom exception types. but such cases are rare. There are cases when swallowing errors in applications is acceptable.avivasolutions. you should allow the application to terminate instead of swallowing the exception. make sure that the object involved stays in a usable and predictable state.nl . AV1041 Do throw the most specific exception that is appropriate For example. Always return an empty array and an empty string instead of a null reference. “Germany” }. The general rule is that null. With usable it is meant that the caller can catch the exception. AV1030 Avoid using friend assemblies Using the [InternalsVisibleTo] attribute can lead to dirty hacks and bypassing basic OO principles. AV1040 Provide a rich and meaningful exception message text The message should explain the cause of the exception and clearly describe what needs to be done to avoid the exception. an empty string ("").avivasolutions. take any necessary actions. and an empty array (0 items) should be treated the same way. private readonly string[] countries = { “Netherlands”.NET Development AV1026 Don’t use readonly fields of arrays If you do. With predictable is meant that the caller can make logical assumptions on the state of the object. AV1027 String and array properties should never return a null reference Returning null can be unexpected by the caller.C# 3. // Will compile and run happily. AV1042 Don’t swallow errors by catching non-specific exceptions Avoid swallowing errors by catching non-specific exceptions. SystemException. The following code example demonstrates how the elements of the read-only array countries can be changed. and continue to use the object again.0 Coding Guidelines Guidelines for . it should throw ArgumentNullException instead of its base type ArgumentException.nl blog. If you cannot predict all possible causes of an exception and ensure that malicious code cannot exploit the resulting application state. but was it intended?? countries[0] = “France”. the array is read-only and cannot be changed. March 2009 Dennis Doomen [5] www. AV1044 Avoid side-effects when throwing recoverable exceptions When you throw a recoverable exception. and so on. but the elements in the array can be changed. // Causes a compile error due to the readonly definition countries = new[] { “Austria” }. in application code. An application should not swallow exceptions that can result in an unexpected or exploitable state. Do only use friend assemblies in well-known solution like the Memento design pattern or to grant unit test code access to certain internal members. such as Exception. if a method receives a null argument. Furthermore don’t pass null as the event data parameter when raising an event.0 Coding Guidelines Guidelines for .nl . Important Derived classes that override the protected virtual method are not required to call the base class implementation. not to structures. AV1061 Don’t generate a semantically different value with a cast For example. AV1053 Consider providing property-changed events Consider providing events that are raised when certain properties are changed. if during the process of adding a new item to a list.avivasolutions. The event handler may have called other methods or properties on you class that changed the object’s state. The base class must continue to work correctly even if its implementation is not called. however.nl blog. AV1051 Do always check an event handler delegate for null An event that has no subscribers is null. If there is no event data. an exception is raised.gif into a Bitmap object using a cast operation. Such an event should be named PropertyChanged. Exception On static events. Always pass a reference to the source (typically this) when raising the event. AV1052 Do use a protected virtual method to raise each event This is applicable only to non-static events on unsealed classes. pass EventArgs. consider implementing the INotifyPropertyChanged interface instead. Complying with this guideline allows derived classes to handle a base class event by overriding the protected method. and another attempt to re-add it is possible. For example. or static events. the sender parameter should be null. sealed classes. the protected virtual method for an event named TimeChanged is named OnTimeChanged.Empty instead of null. The sender argument is then used to get to the source of the event. March 2009 Dennis Doomen [6] www. make sense to convert a file name string such as c:\mybitmap. It does not. The Int32 still represents the time or duration. where Property should be replaced with the name of the property with which this event is associated. so always make sure that the delegate is not null before invoking it.avivasolutions. it is appropriate to convert a Time or TimeSpan into an Int32. AV1060 Do only implement casts that operate on the complete object In other words. Note If your class has many properties that require corresponding events. For example.NET Development For instance. then the caller may safely assume that the item has not been added. AV1050 Don’t make assumptions on the object’s state after raising an event Prepare for any changes to the current object’s state while executing an event handler. AV1054 Don’t pass null as the sender parameter when raising an event Often. a Button class has a string property Name. an event handler is used to handle similar events from multiple senders. The name of the protected virtual method should be the same as the event name prefixed with On. but it is not valid to cast the Button to a string by returning the value of the Name property. It is valid to cast the Button to the Control (since Button is a Control). don’t cast one type to another using a member of the source type.C# 3. you cannot use the == operator to compare multiple GoldMember instances. var q = from customer in db.aspx AV1076 Do evaluate the result of a LINQ expression before returning it Consider the following code snippet public IEnumerable<GoldMember> GetGoldMemberCustomers() { const decimal GoldMemberThresholdInEuro = 1000000. always explicitly evaluate the result of a LINQ query using ToList(). AV1075 Adhere to the LINQ Design Guidelines for custom IQueryable implementations Developing a custom implementation of the IQueryable interface requires a great deal of background information on the . Instead.NET Framework. Make sure you read the guidelines written down by Microsoft on this.NET Framework and the Expression class hierarchy.nl blog.avivasolutions. } } // Do class MyClass<T> where T : SomeClass { void SomeMethod(T t) { SomeClass obj = t. the entire query is re-executed resulting in new instances of GoldMember every time. ToArray() or similar methods. } Since LINQ queries use deferred execution. returning q will actually return the expression tree representing the above query. return q.Customers where customer.msdn.C# 3.Balance > GoldMemberThresholdInEuro select new GoldMember(customer. For example: class SomeClass {} // Don't class MyClass<T> { void SomeMethod(T t) { object temp = t.NET Development AV1062 Avoid casting to and from System. customer.0 Coding Guidelines Guidelines for . this may cause conflicts with future versions of the . Each time the caller evaluates this result using a foreach or something similar.Object in code that uses generics Use where contraints or the as operator instead. See http://blogs. Consequently.com/mirceat/archive/2008/03/13/linq-framework-design-guidelines.Balance).nl .Name. } } AV1070 Don’t add extension methods to the same namespace as the extended class Even though it may seem convenient to add extension methods related to the String class in the System namespace.avivasolutions. SomeClass obj = (SomeClass) temp. March 2009 Dennis Doomen [7] www. As an example.Binding exposed by a certain assembly.dll.cs public partial class MyClass {. For example: Don’t: var list = new System.Generic. All DLLs should be named according to the pattern <Company>.cs public partial class MyClass {. Although technically allowed..avivasolutions. March 2009 Dennis Doomen [8] www.} // In MyClass. For example AvivaSolutions. Do: using System.Binding. Therefore.Core.nl blog.NET Development 3 AV1501 Maintainability Guidelines Avoid using names that can be mistaken with other names. place them after the main class.dll.Generic..Web.} AV1510 Do use using instead of fully qualified type names Limit usage of fully qualified type names to prevent name clashing.<Component>.Collections. use the namespace name as a prefix of the name of the assembly.0 Coding Guidelines Guidelines for . AV1507 Do limit the contents of a source code file to one class Exception It is allowed to place small helper classes such as the ones that provide event data (subclasses of EventArgs) in the same file as the corresponding main class. bool b001 = (lo == l0) ? (I1 == 11) : (lOl != 101).Consulting. name each file after the logical part that part plays.Web.nl .dll where <Company> refers to your company’s name and <Component> contains one or more dot-separated clauses. consider post fixing the assembly with Core.Collections.. AV1505 Do name assemblies after their contained namespace To allow storing assemblies in the Global Assembly Cache (GAC) the filename of an assembly must be unique.Designer. For example: // In MyClass.List<string>(). var list = new List<string>(). AvivaSolutions.dll.Web. AV1508 Do name a source file to the logical function of the partial type When using partial types and allocating a part per file. but do not use that suffix in the namespaces. For instance. consider a group of classes organized under the namespace AvivaSolutions. the following statement is quite confusing. Exception If you decide to combine classes from multiple unrelated namespaces into one assembly.Controls.avivasolutions.C# 3. AV1506 Do name a source file to the class it contains Also. According to this guideline. use Pascal casing for naming the file and don’t use underscores.. that assembly should be called AvivaSolutions. However. avivasolutions. and not subject to future changes. or if the type is very obvious from the same statement and using it would improve readability.0 Coding Guidelines Guidelines for . in your code other than to define symbolic constants. // at 75% // at 75% Don't var i = 3. public const int HighWaterMark = 3 * MaxItems / 4.UI. don’t public class SomeSpecialContainer { public const int MaxItems = 32. either numeric or strings. AV1520 Do use var only when the type is very obvious Only use var as the result of a LINQ query.avivasolutions. public const int MaxNumberOfWheels = 18.NET Development If you do need to prevent name clashing. For example.Label.Create("arg"). // okay // clear enough If the value of one constant depends on the value of another. use a using directive to assign an alias: using Label = System. WaitMilliseconds(waitTimeInSeconds * 1000).Web. } Note An enumeration can often be used for certain types of symbolic constants.C# 3. Literals are allowed when their meaning is clear from the context. } but do public class SomeSpecialContainer { public const int MaxItems = 32. do attempt to make this explicit in the code. For example: mean = (a + b) / 2. public const int HighWaterMark = 24. // // // // what type? int? uint? float? Not obvious what base-class or interface to expect. } Strings intended for logging or tracing are exempt from this rule.WebControls. For example: public class Whatever { public static readonly Color PapayaWhip = new Color(0xFFEFD5).nl .nl blog. Also difficult to refactor if you can't search for the class Do: March 2009 Dennis Doomen [9] www. AV1515 Don’t use "magic numbers" Don’t use literal values. // var imyfoo = MyFactoryMethod. countries. AV1523 Favor Object and Collection Initializers over separate statements Instead of var startInfo = new ProcessStartInfo(“myapp.exe”). but rather define and initialize each variable at the point where it is needed. UseShellExecute = true }. Note Do not violate guideline AV1020 by not providing a proper parameterized constructor.avivasolutions.Add(“Netherlands”). instead of var countries = new List<string>(). process. process. Exception If the value of a constant field must be calculated at run-time (in the static constructor). The compiler inserts the values of const fields directly into the calling code.0 Coding Guidelines Guidelines for . Use Collection Initializers var countries = new List<string> { “Netherlands”. Use Object Initializers var startInfo = new ProcessStartInfo(“myapp.avivasolutions.C# 3. use a static readonly field instead. AV1522 Do use constant fields for variables that will never change Making it const ensures that the same value is used consistently throughout your code.exe”) { StandardOutput = Console. Similarly.UseShellExecute = true. AV1521 Do initialize variables at the point of declaration.Items > 10 and order. and it clarifies the exact meaning of the constant to other co-developers. if possible Avoid the C and Visual Basic styles where all variables have to be defined at the beginning of a block. countries.NET Development var q = from order in orders where order. bad style also wrong where do you stop? OK March 2009 Dennis Doomen [ 10 ] www. For example: while while while while (condition == false) (condition != true) (((condition == true) == true) == true) (condition) // // // // wrong. var list = new ReadOnlyCollection<string>(). var repository = new RepositoryFactory. AV1525 Don’t make explicit comparisons to true or false It is usually bad style to compare a bool-type expression to true or false. In all of three above examples it is clear what type to expect.TotalValue > 1000. which means that const values can never be changed without the risk of introducing a compatibility issue.Output.StandardOutput = Console. For example: private const int MaximumUsers = 100.Output.Get<IOrderRepository>().nl . “United States” }.nl blog.Add(“United States”). avivasolutions. // The right way: if (b1) { if (b2) { Foo(). else Bar(). } } AV1531 Do update loop variables close to where the loop condition is checked This makes understanding the loop much easier. even though the language does not require it. // which „if‟ goes with the „else‟? March 2009 Dennis Doomen [ 11 ] www.NET Development AV1526 Do use an enumeration instead of a list of strings if the list of values is finite If a variable can have a limited set of constant string values. ++index) { if (some condition) { index = 11. --index. do.C# 3. even more so if the loop variable is modified in more than one place. while. AV1530 Don’t change a loop variable inside a for loop block Updating the loop variable within the loop body is generally considered confusing. // Wrong! Use „break‟ or „continue‟ instead. continueLoop = check if some condition is still met. use an enumeration for defining the valid values. an enumerator will typically detect changes to the collection the foreach loop is iteration over. even if it is empty Please note that this also avoids possible confusion in statements of the form: if (b1) if (b2) Foo(). } while ((index > 0) && (continueLoop)) AV1535 Do use a block with all flow control keywords. else.avivasolutions. for (int index = 0. Using the enumeration instead of a constant string allows compile-time checking and prevents typos. bool continueLoop = false. } } Always surround the statements if.nl blog.0 Coding Guidelines Guidelines for . } else { Bar(). index < 10. with a { and a }. for and foreach. int index = 100. do { // Put your loop logic here // Keep these two lines close to the „while‟ statement.nl . Although this rule also applies to foreach loops. For example.avivasolutions. one exit is a sound principle and keeps control flow readable. } } AV1537 Do code every if-else if statement with an else-part The intention of this rule. it may be good practice to exit a method immediately.WriteLine("You answered with Yes"). which applies to else-if constructs. case "yes": Console. For example. } } AV1540 Avoid multiple return statements One entry.WriteLine("You answered with No").0 Coding Guidelines Guidelines for . } else { // What should happen when this point is reached? Ignored? If not. if (val > 0) { pos = true. break.C# 3.NET Development AV1536 Do add a default block after the last case in a switch statement Add a descriptive comment if the default block is supposed to be empty. } else March 2009 Dennis Doomen [ 12 ] www. // throw an InvalidOperationException.nl blog. such as when preconditions are checked and that condition is not met.WriteLine("You answered with Yes"). rather than bool pos. Exception In some cases. if that block is not supposed to be reached throw an InvalidOperationException to detect future changes that may fall through the existing cases.WriteLine("You answered with No"). break. AV1545 Don’t use selection statements instead of a simple assignment or initialization Express your intentions directly. is the same as the previous rule. Moreover. throw new InvalidOperationException("Unexpected answer: " + answer).avivasolutions. This ensures better code. because all paths the code can travel has been thought about. } else if (answer == "yes") { Console. default: // Not supposed to end up here.nl . void Foo(string answer) { if (answer == "no") { Console. void Foo(string answer) { switch (answer) { case "no": Console. Consider for example the following code snippet: public class MyString { private string someText. instead of string result.nl blog.NET Development { pos = false.0 Coding Guidelines Guidelines for . // Better: same scope as length.avivasolutions. public MyString(string s) { this. always explicitly define whether the scope is public. AV1550 Do explicitly define the scope of a type or member Even though types and members have a default scope. } AV1551 Do implement the most complete overload of a method or constructor and call it from the other overloaded methods or constructors This guideline only applies to overloads that are intended for providing optional arguments.nl . private or internal. but more explicit private int height. } public int IndexOf(string s) { March 2009 Dennis Doomen [ 13 ] www. } write bool pos = (val > 0).someText = s. // initialization AV1546 Prefer conditional statements instead of simple if-else constructs For example. if (someString != null) { result = someString. } else { result = “Unavailable”. For example: class Cat {} // Better: same visibility as Cat but more explicit internal class Dog { int length. write return someString ?? “Unavailable”.avivasolutions.C# 3. } return result. int startIndex.IndexOf(s.C# 3. always ensure that this operation does not return null. a method with that many arguments may imply that the responsibilities have not been evenly distributed over the classes in a component. } public int IndexOf(string s.Length . AV1570 Do always check the result of an as operation If you use as to obtain a certain interface reference from an object. count). Notice that the same rule applies to class constructors. int startIndex) { return IndexOf(s.avivasolutions.startIndex ). Failure to do so may cause a NullReferenceException at a much later stage if the object did not implement that interface. Moreover. but two of them simply call the one with the most arguments. 0. } protected virtual int InternalIndexOf(string s. } public int IndexOf(string s. int startIndex. AV1561 Avoid methods with more than 5 arguments If you end up with a method with more than five arguments.0 Coding Guidelines Guidelines for .avivasolutions. int count) { return someText. } } The class MyString provides three overloads for the IndexOf method. int count) { return someText. define the most complete overload as a protected virtual method that is called by all overloads. public class MyString { // same as above … public int IndexOf(string s. March 2009 Dennis Doomen [ 14 ] www.nl .nl blog.IndexOf(s. int count) { return InternalIndexOf(s. startIndex. count). } } AV1560 Do be consistent in the ordering of parameters in overloaded members Parameters with the same name should appear in the same position in all overloads. implement the most complete overload and call that one from the other overloads using the this() operator. Prefer returning compound objects instead. someText. startIndex. Important If you also want to allow derived classes to override these methods. startIndex. someText. count). int startIndex.NET Development return IndexOf(s. use a structure or class for passing multiple arguments. AV1562 Don’t use ref or out parameters Ref and out parameters make code less understandable and therefore may introduce bugs. startIndex.Length). avivasolutions. Class or Struct in a name. For example. AV1708 Identifiers that refer to an array or collection should have a plural name. Code Analysis also performs a spelling check.C# 3. a method in which it is difficult to distinguish local variables from member fields. noun phrases or adjective phrases Do name classes. and value types with nouns. GetLength is a better name than GetInt. noun phrases.0 Coding Guidelines Guidelines for . and don’t give class names a prefix (such as the letter C). such as i or t. AV1707 Do name an identifier according its meaning and not its type Do use semantically interesting names rather than language-specific keywords for type names. For instance. Favor readability over brevity. or occasional adjective phrases. interfaces.avivasolutions.nl . Exceptions Use well-known abbreviations that are widely accepted such as UI instead of UserInterface. is too big. Do name classes. Exception In some languages it may appear counterintuitive to translate domain-specific non-English terms into its English counterparts. The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis). a method that converts data to Int16 should be named ToInt16.NET Development 4 AV1701 Naming Guidelines Do use proper US-English All identifiers should be named using words from the English language. Avoid single character variable names. use OnButtonClick rather than OnBtnClick. Avoid using identifiers that conflict with keywords of widely used programming languages. so you may need to add those terms to a Custom Code Analysis Dictionary. Use index or temp instead. not ToShort because Short is the language-specific type name for Int16. mUserName. m_loginTime. For example. For example. In those cases. Choose easily readable identifier names. For example.and does not explain what its purpose is March 2009 Dennis Doomen [ 15 ] www. Don’t use terms like Enum. However. In general. Bad examples: SearchExamination: in this case it was a page for searching for examinations Common: does not end with a noun. For example. interfaces and value types with nouns. HorizontalAlignment is more readable than AlignmentHorizontal. Examples of incorrect identifier names are: _currentUser. AV1705 Don’t prefix member fields Don’t use a prefix for field names.nl blog. it may be wise to keep the original term from the native language. Don’t use g_ or s_ to distinguish static versus non-static fields. GetZaak for getting a legal case. rather than a language-specific name in the rare cases when an identifier has no semantic meaning beyond its type. Do use a generic Common Type System (CTS) type name. AV1706 Do use abbreviations with care Don’t use abbreviations or acronyms as parts of identifier names. Consider giving a property the same name as its type.0 Coding Guidelines Guidelines for . noun phrases. SmartTextBox. When you have a property that is strongly typed to an enumeration. For instance.C# 3. Consider prefixing Boolean properties with Is. AV1709 Do name generic type parameters with descriptive names The following guidelines cover selecting the correct names for generic type parameters. Do name boolean properties with an affirmative phrase.avivasolutions. AddNewJob() {. unless a single-letter name is completely self explanatory and a descriptive name would not add value. Allows. For example.NET Framework classes Stay close to the naming philosophy of the . Do prefix descriptive type parameter names with the letter T. E. if you define a class that behaves like a collection. a parameter constrained to ISession may be called TSession. Consider indicating constraints placed on a type parameter in the name of parameter.NET Framework.. or Supports.. Use the letter T as the type parameter name for types with one single-letter type parameter.} RegisterForMeeting() {.NET Framework classes use. Can. AV1715 Do properly name properties Do name properties with nouns. so following this same pattern helps them find their way in your classes as well. CanSeek instead of CantSeek. if you have an enumeration named CacheLevel.. Has. Delete or NumberOfItems. or occasionally adjective phrases.avivasolutions.} } AV1711 Do name members similarly to members of .nl . it does not say anything about its purpose Good examples: BusinessBinder. Remove and Count instead of AddItem. For example: IDictionary is an example of an interface that follows this guideline. the name of the property can be the same as the name of the enumeration.} Delete() {.nl blog..} // Also correct.... or EditableSingleCustomer.. AV1710 Don’t repeat the name of a class or enumeration in its members class Employee { // Wrong! static GetEmployee() {} DeleteEmployee() {} // Right static Get() {. Developers are already accustomed to the naming patterns . Do name generic type parameters with descriptive names.g. a property that returns one of its values can also be named CacheLevel. March 2009 Dennis Doomen [ 16 ] www.NET Development SiteSecurity: although the name is technically okay. provide members like Add. For example. and Arriving. don’t use Debug for a namespace name and also provide a class named Debug in the same namespace. For example. the declaration of the Search event may look like this: public event SearchEventHandler Search. a close event that is raised before a window is closed would be called Closing and one that is raised after the window is closed would be called Closed. Don’t use Before or After prefixes or suffixes to indicate pre and post events. AV1735 Do use a verb or verb phrase to name an event Do name events with a verb or a verb phrase.DirectX. Deleted.NET Development AV1720 Do name methods using verb-object pair Name methods using a verb-object pair. Deleted: Occurs when the object is already deleted. Minimizing.nl blog.avivasolutions. March 2009 Dennis Doomen [ 17 ] www.<Feature>][. such as ShowDialog. For example.C# 3. Suppose you want to define events related to the deletion process of an object.(<Product>|<Technology>)[. Avoid defining the Deleting and Deleted events as BeginDelete and EndDelete. Closing. AV1730 Do add the suffix Callback to delegates related to callback methods Delegates that are used to refer to a callback method (so not an event) must be suffixed with Callback. Note Don’t use the same name for a namespace and a type in that namespace.avivasolutions. AV1736 AV1737 Don’t add an Event suffix to the name of an event Do use -ing and -ed to express pre-events and post-events Do give event names a concept of before and after.nl .<Subnamespace>] For instance: Microsoft. A good name should give a hint on the what of a member.0 Coding Guidelines Guidelines for . and if possible. For example: Click. using the present and past tense. Do define those events as follows: Deleting: Occurs just before the object is getting deleted Delete: Occurs when the object needs to be deleted by the event handler. string message). interface IEmployeeRepository { Employee[] First() { } Employee[] GetFirstFive() {} Employee[] GetFiveMostRecent(){} void Add(Employee employee) {} // the } AV1725 // Wrong: What does first mean? How many? // Better // Best: self-describing // Although not using verb-object pair. For example: public delegate void AsyncIOFinishedCallback(IpcClient client. For example. the why. type name is clear enough Do name namespaces according a well-defined pattern All namespaces should be named according to the pattern <Company>.WindowsMobile. AV1745 Group extension methods in a class suffixed with Extensions If the name of an extension method conflicts with another member or extension method.nl .NET Development AV1738 Do prefix an event handler with On It is good practice to prefix the method that handles an event with On. Exception In some situations you might be faced with multiple classes exposing the same event name. For example. March 2009 Dennis Doomen [ 18 ] www.avivasolutions.avivasolutions. Having them in a dedicated class with the Extensions suffix improves readability. as long as it is prefixed with On.C# 3.0 Coding Guidelines Guidelines for . To allow separate event handlers use a more intuitive name for the event handler. you must prefix the call with the class name.nl blog. a method that handles the Closing event could be named OnClosing. 0 Coding Guidelines Guidelines for . then clearly document that. or network interaction. This allows to caller to explicitly cache the result of calling the member and prevent a potential performance issue. March 2009 Dennis Doomen [ 19 ] www. copies that are being made.avivasolutions.nl .nl blog. expensive calculations that are being performed.C# 3.avivasolutions.NET Development 5 AV1800 Performance Guidelines Clearly document if calling a member has a performance impact If calling a member causes a performance impact such as involvement of unmanaged code. description. AV2207 Don’t hardcode strings that change based on the deployment Examples include connection strings. AV2206 Don’t hardcode strings that are presented to end-users Use resources instead.0 Coding Guidelines Guidelines for . AV2216 Do always sign assemblies with a private key Signing an assembly with a private key will give the assembly a strong name which enables the following benefits. etc. AV2205 Do properly name and use resources The guidelines in this topic apply to localizable resources such as error messages and menu text. AV2211 AV2215 Avoid suppressing specific compiler warnings Do properly fill the attributes of the AssemblyInfo. server addresses. the ConnectionStrings property of the ConfigurationManager class.Linq namespace. Classes exposed in the assembly can be exposed to COM. Signed assemblies properly integrate with . copyright statement. March 2009 Dennis Doomen [ 20 ] www. They can be deployed in the Global Assembly Cache.Where(i => i. and int instead of Int32. etc.C# 3.cs file Ensure that the attributes for the company name. are filled. and enable the option Treat warnings as errors. Keep them concise where possible.nl . is to move the corresponding attributes out of the AssemblyInfo. One way to ensure that version and other fields that are common to all assemblies have the same values. Avoid LINQ for simple expressions Rather than var q = from item in items where item.Length > 0). but don’t sacrifice readability. AV2210 Do build with the highest warning level Configure the development environment to use Warning Level 4 for the C# compiler. string instead of String. Do use only alphanumeric characters in naming resources. prefer using the extension methods from the System.nl blog. This allows the compiler to enforce the highest possible code quality.cs into a SolutionInfo.avivasolutions.cs file that is shared by all projects within the solution.Length > 0.NET Development 6 AV2201 Usage Guidelines Do use C# types instead of the types from the System namespace For example: use object instead of Object. version. var q = items. Use Resources.NET security. Do provide descriptive rather than short identifiers. AV2220 Malicious attempts to replace the assembly with another equally named assembly will fail.avivasolutions. or the Settings class generated by Visual Studio. Do use Pascal casing in resource keys. avivasolutions.0 Coding Guidelines Guidelines for .avivasolutions.nl blog.Name == “Tom”.0 and provide a much more elegant alternative for anonymous delegates. c => c. Or even better var customer = customers. use an Lambda expression: Customer c = Array.Find(customers.Name == “Tom”). }).nl . AV2221 Do use Lambda expressions instead of delegates Lambda expressions have been introduced in C# 3.Where(c => c.Name == “Tom”). delegate(Customer c) { return c. So instead of Customer c = Array. March 2009 Dennis Doomen [ 21 ] www.NET Development Since LINQ queries should be written out over multiple lines for readability.C# 3.Find(customers. the second example is a bit more readable. XML element <code> <example> Description Marks a block of text as code. Provides additional details. the overview page of a class will take the summary of the first overload. Add a tag for each type parameter of the generic type or method. XML element <summary> <remarks> <param> <returns> <typeparam> <value> Description Short description of maximum two or three lines. This is an alternative to placing documentation comments directly in your source code file. Inline elements can be used within the contents of the elements from the preceding table. Describes the meaning of a method or constructor argument. by properly documenting your classes. Furthermore.NET Development 7 AV2301 AV2305 Documentation Guidelines Do write comments and documentation in US English Do use XML tags for documenting types and members Document all public types and member of types using the built-in XML comment functionality of Visual Studio. special behaviour. Specifies to comments in another file that describe the types and members in your source code. This element is used to generate an overview page of the members of a class. tools can generate professionally looking class documentation. Without this. including preconditions. Documenting your code allows Visual Studio to pop-up the documentation when your class is used somewhere else. March 2009 Dennis Doomen [ 22 ] www. Specifies which exceptions can be thrown that a caller may catch.0 Coding Guidelines Guidelines for .avivasolutions. The XML elements in the following table are available for documenting a class or class member.nl blog. Indicates that the documentation is preliminary and may change in the near future. Provides a summary for multiple overloads of a method. Describes the type of the data a property accepts or returns. <seealso> <overloads> <event> <exception> <exclude/> <include> Adds an entry to the See Also section at the bottom of a documentation page.C# 3. This commonly involves using the <code> tag. Describes a type parameter for a generic type or method declaration to describe. the relation to other members or classes.nl . These elements can also be used on classes and their members but are used to enrich the documentation.avivasolutions. Describes the return value of a method. Ensures that a member does not appear in generated documentation. Specifies an example of how to use a method or other library member. Indicates which events under which conditions will be raised by a method or property. Describes how a class behaves in a multi-threaded environment. <permission> <preliminary> <threadsafety> Documents the access of a member. nl . External dependencies: is a certain resource (network. AV2308 Do document preconditions Properly document the preconditions for using a class or its members.avivasolutions. Consider the . but can be helpful to add additional comments. also mention that you chose an alternative solution because you ran into a problem with the obvious solution.NET Framework philosophy. Avoid explaining the statements in words. Tip The tool GhostDoc can generate a starting point for documenting code with a shortcut key.NET Framework online help as a good example of how to properly document this. To prevent surprises for the developer. but instead.C# 3.NET Development XML element <see> <paramref> <typeparamref> <note> AV2306 Description Creates a hyperlink to another member or type. try to stay close to the . Creates a reference to a <typeparam> of the current member. March 2009 Dennis Doomen [ 23 ] www. AV2315 AV2316 Do use // for comments Do write comments that explain the purpose of a code block Try to focus comments on the why and what of a code block and not the how. Assume the user will not have access to the source code and try to explain how to get the most out of the functionality of your class. element type of an array.nl blog. AV2310 Do document the exceptions that a member can throw Document the exceptions a member can throw (using the <exception> tag) and explain under which situations it may throw this exception. Do write XML documentation with the caller in mind Write the documentation of your class with the class user in mind. file. Tip You can also define your own tags like <comment>. help the reader understand why you chose a certain solution or algorithm and what you are trying to achieve. Examples include: AV2309 Argument requirements: non-null. an empty string. State/order related: what other members must be called first. Creates a note block with distinct appearance. an empty array or something alike. minimum length of an array. etc. Creates a reference to a <param> of the current member. etc) required? Do document post conditions Document clearly whether a member returns null. They will not be used yet. AV2307 Do write MSDN-style documentation Following the MSDN on-line help style and word choice helps the developer to find its way through your documentation more easily.avivasolutions.0 Coding Guidelines Guidelines for . If applicable. Standard.nl . In order of appearance: 1. static. Control event handlers Page lifecycle handlers March 2009 Dennis Doomen [ 24 ] www.NET Development 8 AV2401 AV2402 Layout Guidelines Don’t put a using statement in a namespace Do order and group namespaces according the company // Microsoft namespaces are first using System.Ajax. Private properties Private methods should be placed behind the public member in calling order. Properties 6. internal. Other members grouped in a functional manner. new. Maintaining a common order allows other team members to find their way in your code more easily. using Telerik. Private fields (in a region) 2. Events 5. Common groups include: a. // Then any other namespaces in alphabetic order using AvivaSolutions. using AvivaSolutions. private. using System. use #regions only for: Private fields (preferably in a Private Definitions region).nl blog. Constructors and the Finalizer 4. using Telerik.avivasolutions. AV2407 Be reluctant with #regions Regions can be helpful. AV2405 Do place modifiers in a well-defined order When multiple modifier keywords are needed in a type or member declaration. virtual. const.avivasolutions. but can also hide to main purpose of a class.Business.0 Coding Guidelines Guidelines for . Page lifecycle handlers c. abstract. Public read-only static fields 3. volatile. readonly.C# 3.Collections. This prevents readers from having to browse up and down through the code file.WebControls. override. AV2406 Order class members in a well-defined pattern. partial. the modifiers should be placed in the following order of appearance: public. sealed. using System. extern. protected. Control event handlers b. Interface implementations (in a #region) 7.XML. Therefore. AV2403 Don’t define multiple namespaces in one file A single file should contribute types to only a single namespace. for. Don’t exceed a line length of 130 characters Do insert space after if. lock and using Do put parentheses on a new line Always put { and } on new lines at the same level of indentation as the keyword they belong to. while. foreach. For example: public string Name { get { return name. Good candidates for an empty line include: AV2411 AV2412 AV2413 Between members After the closing parentheses Between unrelated code blocks Around the #region keyword Between the using statements of the same company. } set { if ((name != null) && (name. a text document with a paragraph break after each one or two sentences is difficult to follow. } } } March 2009 Dennis Doomen [ 25 ] www.Length > 0)) { name = value.nl blog. if (someCondition) { Foo().avivasolutions. catch. property getters and setters that only consist of a single statement may be written in a more compact form.NET Development Nested classes Helper classes (in the same file) Interface implementations (only if the class contains other members) Although not required. So statements or declarations that logically belong to each other should be hold together.0 Coding Guidelines Guidelines for . so don’t overdo.avivasolutions.C# 3. AV2410 Use empty lines wherever considered appropriate See an empty line as a paragraph break in a text document. } Exception To help distinct simple from more complex code.nl . And remember. give the #endregion statement the same name as the #region to improve readability. switch. nl .com http://codebetter.pdf March 2009 Dennis Doomen [ 26 ] www.nl blog. Microsoft http://msdn. The Developer Highway Code. CodeBetter.com/brada/archive/tags/Framework+Design+Guidelines/default.C# 3.se/adddp/ 4.objectmentor.com/en-gb/security/aa473878. Jimmy Nielsen http://www.msdn.com/mirceat/archive/2008/03/13/linq-framework-design-guidelines.avivasolutions.microsoft. Patterns & Practices guidance.com/ 6.NET Framework Design Guidelines.aspx 2.com/resources/articles/lsp.0 Coding Guidelines Guidelines for .aspx 3. .aspx 5. Brad Adams http://blogs. Applying Domain-Driven Design and Patterns in C#.microsoft.avivasolutions. Liskop Substitution Principle http://www.msdn.NET Development 9 Resources 1. LINQ Design Guidelines. Microsoft http://msdn. Mircea Trofin http://blogs.com/en-us/practices/bb969054.aspx 7.jnsk. NET March 2009 Dennis Doomen [ 27 ] www. we made a distinction between the two using the LOB and Fx (framework) columns.nl blog. Design Rules CA1000 DoNotDeclareStaticMembersOnGenericTypes CA1001 TypesThatOwnDisposableFieldsShouldBeDisposable CA1002 DoNotExposeGenericLists CA1003 UseGenericEventHandlerInstances CA1004 GenericMethodsShouldProvideTypeParameter CA1005 AvoidExcessiveParametersOnGenericTypes CA1006 DoNotNestGenericTypesInMemberSignatures CA1007 UseGenericsWhereAppropriate CA1008 EnumsShouldHaveZeroValue CA1009 DeclareEventHandlersCorrectly CA1010 CollectionsShouldImplementGenericInterface CA1011 ConsiderPassingBaseTypesAsParameters CA1012 CA1013 CA1014 CA1016 CA1017 CA1018 CA1019 CA1020 CA1021 CA1023 CA1024 CA1025 CA1026 CA1027 CA1028 CA1030 CA1031 CA1032 CA1033 CA1034 CA1035 CA1036 CA1038 CA1039 CA1040 CA1041 CA1043 CA1044 CA1045 CA1046 CA1047 CA1048 CA1049 CA1050 CA1051 CA1052 CA1053 CA1054 CA1055 CA1056 CA1057 CA1058 CA1059 CA1060 CA1061 CA1062 CA1063 CA1064 AbstractTypesShouldNotHaveConstructors OverloadOperatorEqualsOnOverloadingAddAndSubtract MarkAssembliesWithClsCompliant MarkAssembliesWithAssemblyVersion MarkAssembliesWithComVisible MarkAttributesWithAttributeUsage DefineAccessorsForAttributeArguments AvoidNamespacesWithFewTypes AvoidOutParameters IndexersShouldNotBeMultidimensional UsePropertiesWhereAppropriate ReplaceRepetitiveArgumentsWithParamsArray DefaultParametersShouldNotBeUsed MarkEnumsWithFlags EnumStorageShouldBeInt32 UseEventsWhereAppropriate DoNotCatchGeneralExceptionTypes ImplementStandardExceptionConstructors InterfaceMethodsShouldBeCallableByChildTypes NestedTypesShouldNotBeVisible ICollectionImplementationsHaveStronglyTypedMembers OverrideMethodsOnComparableTypes EnumeratorsShouldBeStronglyTyped ListsAreStronglyTyped AvoidEmptyInterfaces ProvideObsoleteAttributeMessage UseIntegralOrStringArgumentForIndexers PropertiesShouldNotBeWriteOnly DoNotPassTypesByReference DoNotOverloadOperatorEqualsOnReferenceTypes DoNotDeclareProtectedMembersInSealedTypes DoNotDeclareVirtualMembersInSealedTypes TypesThatOwnNativeResourcesShouldBeDisposable DeclareTypesInNamespaces DoNotDeclareVisibleInstanceFields StaticHolderTypesShouldBeSealed StaticHolderTypesShouldNotHaveConstructors UriParametersShouldNotBeStrings UriReturnValuesShouldNotBeStrings UriPropertiesShouldNotBeStrings StringUriOverloadsCallSystemUriOverloads TypesShouldNotExtendCertainBaseTypes MembersShouldNotExposeCertainConcreteTypes MovePInvokesToNativeMethodsClass DoNotHideBaseClassMethods ValidateArgumentsOfPublicMethods ImplementIDisposableCorrectly ExceptionsShouldBePublic LOB x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x Fx x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x Notes Factory methods always violate this rule Often needs overruling if you want to enfore a specific subtype Required to guarantee compliance with VB. Since generic and framework code requires a higher quality than for instance line-of-business applications.avivasolutions.0 Coding Guidelines Guidelines for .C# 3.NET Development 10 List of Code Analysis Rules The table below lists the Visual Studio Code Analysis / FxCop rules that we at Aviva Solutions recommend for any serious software development.nl .avivasolutions. C# 3.nl blog.nl .avivasolutions.0 Coding Guidelines Guidelines for .avivasolutions.NET Development CA1065 DoNotRaiseExceptionsInUnexpectedLocations Globalization Rules CA1300 SpecifyMessageBoxOptions CA1301 AvoidDuplicateAccelerators CA1302 DoNotHardcodeLocaleSpecificStrings CA1304 SpecifyCultureInfo CA1305 SpecifyIFormatProvider CA1306 SetLocaleForDataTypes CA1307 SpecifyStringComparison CA1308 NormalizeStringsToUppercase CA1309 UseOrdinalStringComparison Interoperability Rules CA1400 PInvokeEntryPointsShouldExist CA1401 PInvokesShouldNotBeVisible CA1402 AvoidOverloadsInComVisibleInterfaces CA1403 AutoLayoutTypesShouldNotBeComVisible CA1404 CallGetLastErrorImmediatelyAfterPInvoke CA1405 ComVisibleTypeBaseTypesShouldBeComVisible CA1406 AvoidInt64ArgumentsForVB6Clients CA1407 AvoidStaticMembersInComVisibleTypes CA1408 DoNotUseAutoDualClassInterfaceType CA1409 ComVisibleTypesShouldBeCreatable CA1410 ComRegistrationMethodsShouldBeMatched CA1411 ComRegistrationMethodsShouldNotBeVisible CA1412 MarkComSourceInterfacesAsIDispatch CA1413 AvoidNonpublicFieldsInComVisibleValueTypes CA1414 MarkBooleanPInvokeArgumentsWithMarshalAs CA1415 DeclarePInvokesCorrectly CA2101 SpecifyMarshalingForPInvokeStringArguments Portability Rules CA1900 ValueTypeFieldsShouldBePortable CA1901 PInvokeDeclarationsShouldBePortable Mobility Rules CA1600 DoNotUseIdleProcessPriority CA1601 DoNotUseTimersThatPreventPowerStateChanges Naming Rules CA1700 DoNotNameEnumValuesReserved CA1701 ResourceStringCompoundWordsShouldBeCasedCorrectly CA1702 CompoundWordsShouldBeCasedCorrectly CA1703 ResourceStringsShouldBeSpelledCorrectly CA1704 IdentifiersShouldBeSpelledCorrectly CA1705 LongAcronymsShouldBePascalCased CA1706 ShortAcronymsShouldBeUppercase CA1707 IdentifiersShouldNotContainUnderscores CA1708 IdentifiersShouldDifferByMoreThanCase CA1709 IdentifiersShouldBeCasedCorrectly CA1710 IdentifiersShouldHaveCorrectSuffix CA1711 IdentifiersShouldNotHaveIncorrectSuffix CA1712 DoNotPrefixEnumValuesWithTypeName CA1713 EventsShouldNotHaveBeforeOrAfterPrefix CA1714 FlagsEnumsShouldHavePluralNames CA1715 IdentifiersShouldHaveCorrectPrefix CA1716 IdentifiersShouldNotMatchKeywords CA1717 OnlyFlagsEnumsShouldHavePluralNames CA1718 AvoidLanguageSpecificTypeNamesInParameters CA1719 ParameterNamesShouldNotMatchMemberNames CA1720 AvoidTypeNamesInParameters/IdentifiersShouldNotContainTyp eNames CA1721 PropertyNamesShouldNotMatchGetMethods CA1722 IdentifiersShouldNotHaveIncorrectPrefix CA1724 TypeNamesShouldNotMatchNamespaces CA1725 ParameterNamesShouldMatchBaseDeclaration CA1726 UsePreferredTerms x x o x x o x x Only if you need to handle right-to-left languages o x x o x x DataSets should not be used anymore only if localization is important o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke Only if you use P/Invoke o o o o Only if you use P/Invoke Only if you use P/Invoke x o x o x x x x x x x x x x x x x x x X X X X X X X X X X X x x x x x x x x x x x x x x x x x x x x x x x x x x March 2009 Dennis Doomen [ 28 ] www. nl blog.avivasolutions.NET Development Performance Rules CA1800 DoNotCastUnnecessarily CA1801 ReviewUnusedParameters CA1802 UseLiteralsWhereAppropriate CA1804 RemoveUnusedLocals CA1805 DoNotInitializeUnnecessarily CA1806 DoNotIgnoreMethodResults CA1807 AvoidUnnecessaryStringCreation CA1809 AvoidExcessiveLocals CA1810 InitializeReferenceTypeStaticFieldsInline CA1811 AvoidUncalledPrivateCode CA1812 AvoidUninstantiatedInternalClasses CA1813 AvoidUnsealedAttributes CA1814 PreferJaggedArraysOverMultidimensional CA1815 OverrideEqualsAndOperatorEqualsOnValueTypes CA1816 DisposeMethodsShouldCallSuppressFinalize/CallGCSuppressFi nalizeCorrectly CA1817 DoNotCallPropertiesThatCloneValuesInLoops CA1818 DoNotConcatenateStringsInsideLoops CA1819 PropertiesShouldNotReturnArrays CA1820 TestForEmptyStringsUsingStringLength CA1821 RemoveEmptyFinalizers CA1822 MarkMembersAsStatic CA1823 AvoidUnusedPrivateFields CA1824 MarkAssembliesWithNeutralResourcesLanguage Security Rules CA2100 ReviewSqlQueriesForSecurityVulnerabilities CA2102 CatchNonClsCompliantExceptionsInGeneralHandlers CA2103 ReviewImperativeSecurity CA2104 DoNotDeclareReadOnlyMutableReferenceTypes CA2105 ArrayFieldsShouldNotBeReadOnly CA2106 SecureAsserts CA2107 ReviewDenyAndPermitOnlyUsage CA2108 ReviewDeclarativeSecurityOnValueTypes CA2109 ReviewVisibleEventHandlers CA2110 SecureGetObjectDataOverrides CA2111 PointersShouldNotBeVisible CA2112 SecuredTypesShouldNotExposeFields CA2114 MethodSecurityShouldBeASupersetOfType CA2115 CallGCKeepAliveWhenUsingNativeResources CA2116 AptcaMethodsShouldOnlyCallAptcaMethods CA2117 AptcaTypesShouldOnlyExtendAptcaBaseTypes CA2118 ReviewSuppressUnmanagedCodeSecurityUsage CA2119 SealMethodsThatSatisfyPrivateInterfaces CA2120 SecureSerializationConstructors CA2121 StaticConstructorsShouldBePrivate CA2122 DoNotIndirectlyExposeMethodsWithLinkDemands CA2123 OverrideLinkDemandsShouldBeIdenticalToBase CA2124 WrapVulnerableFinallyClausesInOuterTry CA2126 TypeLinkDemandsRequireInheritanceDemands CA2127 SecurityTransparentAssembliesShouldNotContainSecurity CriticalCode CA2128 SecurityTransparentCodeShouldNotAssert CA2129 SecurityTransparentCodeShouldNotReferenceNonpublicSecurity CriticalCode Usage Rules CA2200 RethrowToPreserveStackDetails CA2201 DoNotRaiseReservedExceptionTypes CA2202 DoNotDisposeObjectsMultipleTimes CA2204 LiteralsShouldBeSpelledCorrectly CA2205 UseManagedEquivalentsOfWin32Api CA2207 InitializeValueTypeStaticFieldsInline CA2208 InstantiateArgumentExceptionsCorrectly CA2210 AssembliesShouldHaveValidStrongNames CA2211 NonConstantFieldsShouldNotBeVisible CA2212 DoNotMarkServicedComponentsWithWebMethod CA2213 DisposableFieldsShouldBeDisposed CA2214 DoNotCallOverridableMethodsInConstructors CA2215 DisposeMethodsShouldCallBaseClassDispose X X X X X X X X X X X X X X X X X X X X X X x x x x x x x x Far fetched x x x x x x x x x x x x x x X X X X x x x x x x x x x o x x o x x x x x x x x x x x x x Use a O/R Mapper instead X X O Only if you use P/Invoke O Only if you use P/Invoke X X Is already checked by the compiler x x x x x x x x x x x x x x x x x x x x x x x x x x Always violated by NHibernate entities March 2009 Dennis Doomen [ 29 ] www.nl .C# 3.avivasolutions.0 Coding Guidelines Guidelines for . NET Development CA2216 CA2217 CA2218 CA2219 CA2220 CA2221 CA2222 CA2223 CA2224 CA2225 CA2226 CA2227 CA2228 CA2229 CA2230 CA2231 CA2232 CA2233 CA2234 CA2235 CA2236 CA2237 CA2238 CA2239 CA2240 CA2241 CA2242 CA2243 DisposableTypesShouldDeclareFinalizer DoNotMarkEnumsWithFlags OverrideGetHashCodeOnOverridingEquals DoNotRaiseExceptionsInExceptionClauses6 FinalizersShouldCallBaseClassFinalizer FinalizersShouldBeProtected DoNotDecreaseInheritedMemberVisibility MembersShouldDifferByMoreThanReturnType OverrideEqualsOnOverloadingOperatorEquals OperatorOverloadsHaveNamedAlternates OperatorsShouldHaveSymmetricalOverloads CollectionPropertiesShouldBeReadOnly DoNotShipUnreleasedResourceFormats ImplementSerializationConstructors UseParamsForVariableArguments OverloadOperatorEqualsOnOverridingValueTypeEquals MarkWindowsFormsEntryPointsWithStaThread OperationsShouldNotOverflow PassSystemUriObjectsInsteadOfStrings MarkAllNonSerializableFields CallBaseClassMethodsOnISerializableTypes MarkISerializableTypesWithSerializable ImplementSerializationMethodsCorrectly ProvideDeserializationMethodsForOptionalFields ImplementISerializableCorrectly ProvideCorrectArgumentsToFormattingMethods TestForNaNCorrectly AttributeStringLiteralsShouldParseCorrectly x x x x x x x x x o x x x x x x x x x x x x x x x x x x x x x x x x x x x o x x x x x x x x x x x x x x x x x x Is automatically done by the C# compiler Is automatically done by the C# compiler Only if you target other languages than C# and VB.C# 3.0 Coding Guidelines Guidelines for .avivasolutions.nl .NET Maintainability Rules CA1500 VariableNamesShouldNotMatchFieldNames CA1501 AvoidExcessiveInheritance CA1502 AvoidExcessiveComplexity CA1504 ReviewMisleadingFieldNames CA1505 AvoidUnmaintainableCode CA1506 AvoidExcessiveClassCoupling Reliability Rules CA2000 DisposeObjectsBeforeLosingScope CA2001 AvoidCallingProblematicMethods CA2002 DoNotLockOnObjectsWithWeakIdentity CA2003 DoNotTreatFibersAsThreads CA2004 RemoveCallsToGCKeepAlive CA2006 UseSafeHandleToEncapsulateNativeResources x x x x x x x x x x x x x x x x x x x x x x x x March 2009 Dennis Doomen [ 30 ] www.avivasolutions.nl blog.